RUST Telekinesis v3.3.0

Features​

• Allows players with permission to move and rotate entities in place
• Allows restricting capabilities with configurable rulesets

Abuse warning​

This plugin can be abused if the permissions are granted to normal players, so it's recommended to grant the permissions to only trusted admins or moderators.

Performance warning​

This plugin can degrade server performance, especially when multiple players are moving entities simultaneously, so it's recommended that you use this plugin sparingly.

Permissions​

This plugin uses the permission system. To assign a permission, use oxide.grant <user or group> <name or steam id> <permission>. To remove a permission, use oxide.revoke <user or group> <name or steam id> <permission>.

• telekinesis.admin -- Allows unrestricted usage of the tls command.
• telekinesis.ruleset.restricted -- Allows restricted usage of the tls command. The restrictions are controlled by the plugin configuration.

You may create additional rulesets in the plugin configuration, each of which will generate a separate permission of the format telekinesis.ruleset.<suffix>. Granting multiple rulesets to a player will cause only the last one to apply, based on the order in the config.

Usage​

1. Run the tls command to grab the entity you are looking at. The entity will automatically move wherever your player camera goes.
2. Press primary attack (mouse1) or secondary attack (mouse2) to move or rotate the entity (depending on which mode is active).
3. While moving or rotating the entity, hold duck (Ctrl) to move/rotate slowly, or sprint (Shift) to move/rotate quickly.
4. Press the reload key to switch between modes. Holding sprint while pressing reload will change modes in reverse order. See below for details about each mode.
5. Run the tls command again to release the entity.
6. Run the tls undo command to reset the position/rotation of the entity you are currently controlling, or to reset the last entity that you controlled.

Modes​

• "Move away/toward" -- Moves the entity away from you or toward you, in the direction that you are looking.
• "Move up/down" -- Moves the entity up or down, using the world Y axis, regardless of where you are looking, and regardless of the entity's rotation.
• "Rotate around X axis (pitch)" -- Rotate the entity around its own X axis. This basically tilts it forward or backward.
• "Rotate around Y axis (yaw)" -- Rotate the entity around its own Y axis. This basically turns it left or right.
• "Rotate around Z axis (roll)" -- Rotate the entity around its own Z axis. This basically leans it left or right.

Commands​

This plugin provides both chat and console commands using the same syntax. When using a command in chat, prefix it with a forward slash: `/`.

• tls -- Grabs the entity you are looking at, or releases the entity you are currently controlling.
• tls undo -- Resets the most recently grabbed entity to its original position and rotation. This can only be done if you moved or rotated the entity in the past 5 minutes.

Configuration​

The settings and options can be configured in the Telekinesis file under the config directory. The use of an editor and validator is recommended to avoid formatting issues and syntax errors.
Default configuration:

• Enable message prefix -- Enable or disable the chat/console message prefix. The prefix itself can be configured in the localization.
• Idle timeout (seconds) -- Determines how long you can be inactive (no entity movement or rotation) until the entity you are controlling is automatically released.
• Building privilege check frequency (seconds) -- Determines how often to check for building privilege when using a ruleset that disallows usage while building blocked. Note: Building privilege checks are costly to server performance, so you should avoid setting this value very low.
• Move sensitivity -- Determines how quickly you can move the held entity when using the "Move away/toward" or "Move up/down" modes. These settings do not affect how quickly the entity moves when you move your player or change your view angles.
  • Slow -- Applies while holding the duck key (Ctrl by default).
  • Normal -- Applies while not holding the sprint or duck keys.
  • Fast -- Applies while holding the sprint key (Shift by default).
• Rotate sensitivity -- Determines how quickly you can rotate the held entity when using any of the rotate modes.
• Rulesets -- Rulesets can be assigned to players via permissions, in order to restrict their usage.
  • Permission suffix -- Determines the permission associated with the ruleset, which will be generated using the format telekinesis.ruleset.<suffix>.
  • Can move players (true/false) -- Determines whether players with this ruleset are allowed to move other players (sleeping or awake).
  • Can use while building blocked (true/false) -- Determines whether players with this ruleset are allowed to move entities while they are building blocked (i.e., while they are nearby an enemy TC).
  • Requires ownership (true/false) -- Determines whether players with this ruleset must own the entities they want to move.
  • Max distance -- Determines how far away players with this ruleset can pick up and move entities. This applies when trying to pick up the entity, as well as when using the "Move away/toward" and "Move up/down" modes.

Localization​

The default messages are in the Telekinesis file under the lang/en directory. To add support for another language, create a new language folder (e.g. de for German) if not already created, copy the default language file to the new folder and then customize the messages.

Developer API​

API_IsBeingControlled​

Returns true if the entity is being controlled with Telekinesis, else returns false.

API_IsUsingTelekinesis​

Returns true if the player is controlling an entiy with Telekinesis, else returns false.

API_StartAdminTelekinesis​

Starts a Telekinesis session for the specified player and entity, with no restrictions. This is the same as if the player had the telekinesis.admin and used the tls command on the entity. Returns true if the session was able to be started, else returns false.

Possible reasons for returning false:

• The entity was already being controlled by Telekinesis.
• The player was already controlling an entity with Telekinesis.
• Another plugin blocked it with the CanStartTelekinesis hook.

API_StopPlayerTelekinesis​

Stops a Telekinesis session for the specified player. Has no effect if the player was not using Telekinesis.

API_StopTargetTelekinesis​

Stops a Telekinesis session for the specified target entity. Has no effect if the entity was not being controlled by Telekinesis.

Developer Hooks​

OnTelekinesisFindFailed​

• Called after Telekinesis failed to find any entity where the player was looking.
• Returning a BaseEntity will cause Telekinesis to grab that entity.
• Returning null will result in the default behavior.
• This is useful for specific plugins to provide entities that have no collider.

OnTelekinesisStart​

• Called after Telekinesis has found a target entity, before the session has started.
• Returning a BaseEntity will cause Telekinesis to grab that entity instead of the one that was found.
• Returning null will use the entity that Telekinesis found, or one that another plugin provided.
• This is useful to swap out which entity is going to be controlled. For example, to control a parent entity instead of the child.

CanStartTelekinesis​

• Called when a Telekinesis session is about to start.
• Returning false or a string will prevent the Telekinesis session from starting. If returning a string, the value will be sent to the player as a chat message.
• Returning null will allow the session to start, unless another plugin blocks it.

OnTelekinesisStarted​

• Called after a Telekinesis session has started.
• No return behavior.

OnTelekinesisStopped​

• Called after a Telekinesis session has ended.
• No return behavior.