VRTK_MoveTransformGrabAttach

extends VRTK_BaseGrabAttach

Overview

Moves the Transform of the Interactable Object towards the interacting object within specified limits.

To allow unrestricted movement, set the axis limit minimum to -infinity and the axis limit maximum to infinity.

Script Usage:

• Place the VRTK_MoveTransformGrabAttach script on either:
  • The GameObject of the Interactable Object to detect interactions on.
  • Any other scene GameObject and then link that GameObject to the Interactable Objects Grab Attach Mechanic Script parameter to denote use of the grab mechanic.

Inspector Parameters

• Detach Distance: The maximum distance the grabbing object is away from the Interactable Object before it is automatically released.
• Tracking Speed: The speed in which to track the grabbed Interactable Object to the interacting object.
• Force Kinematic On Grab: If this is checked then it will force the rigidbody on the Interactable Object to be Kinematic when the grab occurs.
• Release Deceleration Damper: The damper in which to slow the Interactable Object down when released to simulate continued momentum. The higher the number, the faster the Interactable Object will come to a complete stop on release.
• Reset To Orign On Release Speed: The speed in which the Interactable Object returns to it's origin position when released. If the Reset To Orign On Release Speed is 0f then the position will not be reset.
• X Axis Limits: The minimum and maximum limits the Interactable Object can be moved along the x axis.
• Y Axis Limits: The minimum and maximum limits the Interactable Object can be moved along the y axis.
• Z Axis Limits: The minimum and maximum limits the Interactable Object can be moved along the z axis.
• Min Max Threshold: The threshold the position value needs to be within to register a min or max position value.
• Min Max Normalized Threshold: The threshold the normalized position value needs to be within to register a min or max normalized position value.

Class Variables

• public Vector3 localOrigin - The default local position of the Interactable Object.

Class Events

• TransformPositionChanged - Emitted when the Transform position has changed.
• XAxisMinLimitReached - Emitted when the Transform position has reached the X Axis Min Limit.
• XAxisMinLimitExited - Emitted when the Transform position has exited the X Axis Min Limit.
• XAxisMaxLimitReached - Emitted when the Transform position has reached the X Axis Max Limit.
• XAxisMaxLimitExited - Emitted when the Transform position has exited the X Axis Max Limit.
• YAxisMinLimitReached - Emitted when the Transform position has reached the Y Axis Min Limit.
• YAxisMinLimitExited - Emitted when the Transform position has exited the Y Axis Min Limit.
• YAxisMaxLimitReached - Emitted when the Transform position has reached the Y Axis Max Limit.
• YAxisMaxLimitExited - Emitted when the Transform position has exited the Y Axis Max Limit.
• ZAxisMinLimitReached - Emitted when the Transform position has reached the Z Axis Min Limit.
• ZAxisMinLimitExited - Emitted when the Transform position has exited the Z Axis Min Limit.
• ZAxisMaxLimitReached - Emitted when the Transform position has reached the Z Axis Max Limit.
• ZAxisMaxLimitExited - Emitted when the Transform position has exited the Z Axis Max Limit.

Unity Events

Adding the VRTK_MoveTransformGrabAttach_UnityEvents component to VRTK_MoveTransformGrabAttach object allows access to UnityEvents that will react identically to the Class Events.

• All C# delegate events are mapped to a Unity Event with the On prefix. e.g. MyEvent -> OnMyEvent.

Event Payload

• GameObject interactingObject - The GameObject that is performing the interaction (e.g. a controller).
• Vector3 position - The current position in relation to the axis limits from the origin position.
• Vector3 normalizedPosition - The normalized position (between 0f and 1f) of the Interactable Object in relation to the axis limits.
• Vector3 currentDirection - The direction vector that the Interactable Object is currently moving across the axes in.
• Vector3 originDirection - The direction vector that the Interactable Object is currently moving across the axes in in relation to the origin position.

Class Methods

StartGrab/3

public override bool StartGrab(GameObject grabbingObject, GameObject givenGrabbedObject, Rigidbody givenControllerAttachPoint)

• Parameters
  • GameObject grabbingObject - The GameObject that is doing the grabbing.
  • GameObject givenGrabbedObject - The GameObject that is being grabbed.
  • Rigidbody givenControllerAttachPoint - The point on the grabbing object that the grabbed object should be attached to after grab occurs.
• Returns
  • bool - Returns true if the grab is successful, false if the grab is unsuccessful.

The StartGrab method sets up the grab attach mechanic as soon as an Interactable Object is grabbed.

StopGrab/1

public override void StopGrab(bool applyGrabbingObjectVelocity)

• Parameters
  • bool applyGrabbingObjectVelocity - If true will apply the current velocity of the grabbing object to the grabbed object on release.
• Returns
  • none

The StopGrab method ends the grab of the current Interactable Object and cleans up the state.

CreateTrackPoint/4

public override Transform CreateTrackPoint(Transform controllerPoint, GameObject currentGrabbedObject, GameObject currentGrabbingObject, ref bool customTrackPoint)

• Parameters
  • Transform controllerPoint - The point on the controller where the grab was initiated.
  • GameObject currentGrabbedObject - The GameObject that is currently being grabbed.
  • GameObject currentGrabbingObject - The GameObject that is currently doing the grabbing.
  • ref bool customTrackPoint - A reference to whether the created track point is an auto generated custom object.
• Returns
  • Transform - The Transform of the created track point.

The CreateTrackPoint method sets up the point of grab to track on the grabbed object.

ProcessUpdate/0

public override void ProcessUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessUpdate method is run in every Update method on the Interactable Object.

GetPosition/0

public virtual Vector3 GetPosition()

• Parameters
  • none
• Returns
  • Vector3 - A Vector3 containing the current Transform position in relation to the axis limits.

The GetPosition method returns a Vector3 of the Transform position in relation to the axis limits.

GetNormalizedPosition/0

public virtual Vector3 GetNormalizedPosition()

• Parameters
  • none
• Returns
  • Vector3 - A normalized Vector3 of the Transform position in relation to the axis limits.

The GetNormalizedPosition method returns a Vector3 of the Transform position normalized between 0f and 1f in relation to the axis limits.;

GetCurrentDirection/0

public virtual Vector3 GetCurrentDirection()

• Parameters
  • none
• Returns
  • Vector3 - A Vector3 of the direction the Transform is moving across the relevant axis in.

The GetCurrentDirection method returns a Vector3 of the current positive/negative axis direction that the Transform is moving in.

GetDirectionFromOrigin/0

public virtual Vector3 GetDirectionFromOrigin()

• Parameters
  • none
• Returns
  • Vector3 - A Vector3 of the direction the Transform is moving across the relevant axis in relation to the original position.

The GetDirectionFromOrigin method returns a Vector3 of the direction across the axis from the original position.

SetCurrentPosition/2

public virtual void SetCurrentPosition(Vector3 newPosition, float speed)

• Parameters
  • Vector3 newPosition - The position to move the Interactable Object to.
  • float speed - The speed in which to move the Interactable Object.
• Returns
  • none

The SetCurrentPosition method sets the position of the Interactable Object to the given new position at the appropriate speed.

ResetPosition/0

public virtual void ResetPosition()

• Parameters
  • none
• Returns
  • none

The ResetPosition method will move the Interactable Object back to the origin position.

GetWorldLimits/0

public virtual Limits2D[] GetWorldLimits()

• Parameters
  • none
• Returns
  • Limits2D[] - An array of axis limits in world space.

The GetWorldLimits method returns an array of minimum and maximum axis limits for the Interactable Object in world space.