Grab Attach Mechanics (VRTK/Scripts/Interactions/GrabAttachMechanics)

This directory contains scripts that are used to provide different mechanics to apply when grabbing an interactable object.

• Base Grab Attach
• Base Joint Grab Attach
• Fixed Joint Grab Attach
• Spring Joint Grab Attach
• Custom Joint Grab Attach
• Child Of Controller Grab Attach
• Track Object Grab Attach
• Rotator Track Grab Attach
• Climbable Grab Attach

---

Base Grab Attach (VRTK_BaseGrabAttach)

Overview

The Base Grab Attach script is an abstract class that all grab attach script inherit.

As this is an abstract class, it cannot be applied directly to a game object and performs no logic.

Inspector Parameters

• Precision Grab: If this is checked then when the controller grabs the object, it will grab it with precision and pick it up at the particular point on the object the controller is touching.
• Right Snap Handle: A Transform provided as an empty game object which must be the child of the item being grabbed and serves as an orientation point to rotate and position the grabbed item in relation to the right handed controller. If no Right Snap Handle is provided but a Left Snap Handle is provided, then the Left Snap Handle will be used in place. If no Snap Handle is provided then the object will be grabbed at its central point. Not required for Precision Snap.
• Left Snap Handle: A Transform provided as an empty game object which must be the child of the item being grabbed and serves as an orientation point to rotate and position the grabbed item in relation to the left handed controller. If no Left Snap Handle is provided but a Right Snap Handle is provided, then the Right Snap Handle will be used in place. If no Snap Handle is provided then the object will be grabbed at its central point. Not required for Precision Snap.
• Throw Velocity With Attach Distance: If checked then when the object is thrown, the distance between the object’s attach point and the controller’s attach point will be used to calculate a faster throwing velocity.
• Throw Multiplier: An amount to multiply the velocity of the given object when it is thrown. This can also be used in conjunction with the Interact Grab Throw Multiplier to have certain objects be thrown even further than normal (or thrown a shorter distance if a number below 1 is entered).
• On Grab Collision Delay: The amount of time to delay collisions affecting the object when it is first grabbed. This is useful if a game object may get stuck inside another object when it is being grabbed.

Class Methods

IsTracked/0

public bool IsTracked()

• Parameters
  • none
• Returns
  • bool – Is true if the mechanic is of type tracked.

The IsTracked method determines if the grab attach mechanic is a track object type.

IsClimbable/0

public bool IsClimbable()

• Parameters
  • none
• Returns
  • bool – Is true if the mechanic is of type climbable.

The IsClimbable method determines if the grab attach mechanic is a climbable object type.

IsKinematic/0

public bool IsKinematic()

• Parameters
  • none
• Returns
  • bool – Is true if the mechanic is of type kinematic.

The IsKinematic method determines if the grab attach mechanic is a kinematic object type.

ValidGrab/1

public virtual bool ValidGrab(Rigidbody checkAttachPoint)

• Parameters
  • Rigidbody checkAttachPoint –
• Returns
  • bool – Always returns true for the base check.

The ValidGrab method determines if the grab attempt is valid.

SetTrackPoint/1

public virtual void SetTrackPoint(Transform givenTrackPoint)

• Parameters
  • Transform givenTrackPoint – The track point to set on the grabbed object.
• Returns
  • none

The SetTrackPoint method sets the point on the grabbed object where the grab is happening.

SetInitialAttachPoint/1

public virtual void SetInitialAttachPoint(Transform givenInitialAttachPoint)

• Parameters
  • Transform givenInitialAttachPoint – The point where the initial grab took place.
• Returns
  • none

The SetInitialAttachPoint method sets the point on the grabbed object where the initial grab happened.

StartGrab/3

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

• Parameters
  • GameObject grabbingObject – The object that is doing the grabbing.
  • GameObject givenGrabbedObject – The object 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 – Is 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 object is grabbed.

StopGrab/1

public virtual 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 object and cleans up the state.

CreateTrackPoint/4

public virtual 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 object that is currently being grabbed.
  • GameObject currentGrabbingObject – The object 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 virtual void ProcessUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessUpdate method is run in every Update method on the interactable object.

ProcessFixedUpdate/0

public virtual void ProcessFixedUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessFixedUpdate method is run in every FixedUpdate method on the interactable object.

---

Base Joint Grab Attach (VRTK_BaseJointGrabAttach)

extends VRTK_BaseGrabAttach

Overview

The Base Joint Grab Attach script is an abstract class that all joint grab attach types inherit.

As this is an abstract class, it cannot be applied directly to a game object and performs no logic.

Inspector Parameters

• Destroy Immediately On Throw: Determines whether the joint should be destroyed immediately on release or whether to wait till the end of the frame before being destroyed.

Class Methods

ValidGrab/1

public override bool ValidGrab(Rigidbody checkAttachPoint)

• Parameters
  • Rigidbody checkAttachPoint –
• Returns
  • bool – Returns true if there is no current grab happening, or the grab is initiated by another grabbing object.

The ValidGrab method determines if the grab attempt is valid.

StartGrab/3

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

• Parameters
  • GameObject grabbingObject – The object that is doing the grabbing.
  • GameObject givenGrabbedObject – The object 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 – Is 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 object is grabbed. It is also responsible for creating the joint on the grabbed object.

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 object and cleans up the state. It is also responsible for removing the joint from the grabbed object.

---

Fixed Joint Grab Attach (VRTK_FixedJointGrabAttach)

extends VRTK_BaseJointGrabAttach

Overview

The Fixed Joint Grab Attach script is used to create a simple Fixed Joint connection between the object and the grabbing object.

Inspector Parameters

• Break Force: Maximum force the joint can withstand before breaking. Infinity means unbreakable.

Example

VRTK/Examples/005_Controller_BasicObjectGrabbing demonstrates this grab attach mechanic all of the grabbable objects in the scene.

---

Spring Joint Grab Attach (VRTK_SpringJointGrabAttach)

extends VRTK_BaseJointGrabAttach

Overview

The Spring Joint Grab Attach script is used to create a simple Spring Joint connection between the object and the grabbing object.

Inspector Parameters

• Break Force: Maximum force the joint can withstand before breaking. Infinity means unbreakable.
• Strength: The strength of the spring.
• Damper: The amount of dampening to apply to the spring.

Example

VRTK/Examples/021_Controller_GrabbingObjectsWithJoints demonstrates this grab attach mechanic on the Drawer object in the scene.

---

Custom Joint Grab Attach (VRTK_CustomJointGrabAttach)

extends VRTK_BaseJointGrabAttach

Overview

The Custom Joint Grab Attach script allows a custom joint to be provided for the grab attach mechanic.

The custom joint is placed on the interactable object and at runtime the joint is copied into a JointHolder game object that becomes a child of the interactable object.

The custom joint is then copied from this JointHolder to the interactable object when a grab happens and is removed when a grab ends.

Inspector Parameters

• Custom Joint: The joint to use for the grab attach joint.

Example

VRTK/Examples/021_Controller_GrabbingObjectsWithJoints demonstrates this grab attach mechanic on the Lamp object in the scene.

---

Child Of Controller Grab Attach (VRTK_ChildOfControllerGrabAttach)

extends VRTK_BaseGrabAttach

Overview

The Child Of Controller Grab Attach script is used to make the grabbed object a child of the grabbing object upon grab.

The object upon grab will naturally track the position and rotation of the grabbing object as it is a child of the grabbing game object.

The rigidbody of the object will be set to kinematic upon grab and returned to it’s original state on release.

Class Methods

StartGrab/3

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

• Parameters
  • GameObject grabbingObject – The object that is doing the grabbing.
  • GameObject givenGrabbedObject – The object 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 – Is 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 object is grabbed. It is also responsible for creating the joint on the grabbed object.

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 object and cleans up the state.

Example

VRTK/Examples/023_Controller_ChildOfControllerOnGrab uses this grab attach mechanic for the bow and the arrow.

---

Track Object Grab Attach (VRTK_TrackObjectGrabAttach)

extends VRTK_BaseGrabAttach

Overview

The Track Object Grab Attach script doesn’t attach the object to the controller via a joint, instead it ensures the object tracks the direction of the controller.

This works well for items that are on hinged joints or objects that require to interact naturally with other scene rigidbodies.

Inspector Parameters

• Detach Distance: The maximum distance the grabbing controller is away from the object before it is automatically dropped.
• Velocity Limit: The maximum amount of velocity magnitude that can be applied to the object. Lowering this can prevent physics glitches if objects are moving too fast.
• Angular Velocity Limit: The maximum amount of angular velocity magnitude that can be applied to the object. Lowering this can prevent physics glitches if objects are moving too fast.

Class Methods

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 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 object that is currently being grabbed.
  • GameObject currentGrabbingObject – The object 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. It is responsible for checking if the tracked object has exceeded it’s detach distance.

ProcessFixedUpdate/0

public override void ProcessFixedUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessFixedUpdate method is run in every FixedUpdate method on the interactable object. It applies velocity to the object to ensure it is tracking the grabbing object.

Example

VRTK/Examples/021_Controller_GrabbingObjectsWithJoints demonstrates this grab attach mechanic on the Chest handle and Fire Extinguisher body.

---

Rotator Track Grab Attach (VRTK_RotatorTrackGrabAttach)

extends VRTK_TrackObjectGrabAttach

Overview

The Rotator Track Grab Attach script is used to track the object but instead of the object tracking the direction of the controller, a force is applied to the object to cause it to rotate.

This is ideal for hinged joints on items such as wheels or doors.

Class Methods

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 object and cleans up the state.

ProcessFixedUpdate/0

public override void ProcessFixedUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessFixedUpdate method is run in every FixedUpdate method on the interactable object. It applies a force to the grabbed object to move it in the direction of the grabbing object.

Example

VRTK/Examples/021_Controller_GrabbingObjectsWithJoints demonstrates this grab attach mechanic on the Wheel and Door objects in the scene.

---

Climbable Grab Attach (VRTK_ClimbableGrabAttach)

extends VRTK_BaseGrabAttach

Overview

The Climbable Grab Attach script is used to mark the object as a climbable interactable object.

Example

VRTK/Examples/037_CameraRig_ClimbingFalling uses this grab attach mechanic for each item that is climbable in the scene.

---

Secondary Controller Grab Actions (VRTK/Scripts/Interactions/SecondaryControllerGrabActions)

This directory contains scripts that are used to provide different actions when a secondary controller grabs a grabbed object.

• Base Grab Action
• Swap Controller Grab Action
• Axis Scale Grab Action
• Control Direction Grab Action

---

Base Grab Action (VRTK_BaseGrabAction)

Overview

The Base Grab Action is an abstract class that all other secondary controller actions inherit and are required to implement the public abstract methods.

As this is an abstract class, it cannot be applied directly to a game object and performs no logic.

Class Methods

Initialise/5

public virtual void Initialise(VRTK_InteractableObject currentGrabbdObject, VRTK_InteractGrab currentPrimaryGrabbingObject, VRTK_InteractGrab currentSecondaryGrabbingObject, Transform primaryGrabPoint, Transform secondaryGrabPoint)

• Parameters
  • VRTK_InteractableObject currentGrabbdObject – The Interactable Object script for the object currently being grabbed by the primary controller.
  • VRTK_InteractGrab currentPrimaryGrabbingObject – The Interact Grab script for the object that is associated with the primary controller.
  • VRTK_InteractGrab currentSecondaryGrabbingObject – The Interact Grab script for the object that is associated with the secondary controller.
  • Transform primaryGrabPoint – The point on the object where the primary controller initially grabbed the object.
  • Transform secondaryGrabPoint – The point on the object where the secondary controller initially grabbed the object.
• Returns
  • none

The Initalise method is used to set up the state of the secondary action when the object is initially grabbed by a secondary controller.

ResetAction/0

public virtual void ResetAction()

• Parameters
  • none
• Returns
  • none

The ResetAction method is used to reset the secondary action when the object is no longer grabbed by a secondary controller.

IsActionable/0

public bool IsActionable()

• Parameters
  • none
• Returns
  • bool – Is true if the secondary grab action does perform an action on secondary grab.

The IsActionable method is used to determine if the secondary grab action performs an action on grab.

IsSwappable/0

public bool IsSwappable()

• Parameters
  • none
• Returns
  • bool – Is true if the grab action allows swapping to another grabbing object.

The IsSwappable method is used to determine if the secondary grab action allows to swab the grab state to another grabbing object.

ProcessUpdate/0

public virtual void ProcessUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessUpdate method runs in every Update on the Interactable Object whilst it is being grabbed by a secondary controller.

ProcessFixedUpdate/0

public virtual void ProcessFixedUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessFixedUpdate method runs in every FixedUpdate on the Interactable Object whilst it is being grabbed by a secondary controller.

OnDropAction/0

public virtual void OnDropAction()

• Parameters
  • none
• Returns
  • none

The OnDropAction method is executed when the current grabbed object is dropped and can be used up to clean up any secondary grab actions.

---

Swap Controller Grab Action (VRTK_SwapControllerGrabAction)

extends VRTK_BaseGrabAction

Overview

The Swap Controller Grab Action provides a mechanism to allow grabbed objects to be swapped between controllers.

Example

VRTK/Examples/005_Controller_BasicObjectGrabbing demonstrates the ability to swap objects between controllers on grab.

---

Axis Scale Grab Action (VRTK_AxisScaleGrabAction)

extends VRTK_BaseGrabAction

Overview

The Axis Scale Grab Action provides a mechanism to scale objects when they are grabbed with a secondary controller.

Inspector Parameters

• Ungrab Distance: The distance the secondary controller must move away from the original grab position before the secondary controller auto ungrabs the object.
• Lock X Axis: If checked the current X Axis of the object won’t be scaled
• Lock Y Axis: If checked the current Y Axis of the object won’t be scaled
• Lock Z Axis: If checked the current Z Axis of the object won’t be scaled
• Uniform Scaling: If checked all the axes will be scaled together (unless locked)

Class Methods

Initialise/5

public override void Initialise(VRTK_InteractableObject currentGrabbdObject, VRTK_InteractGrab currentPrimaryGrabbingObject, VRTK_InteractGrab currentSecondaryGrabbingObject, Transform primaryGrabPoint, Transform secondaryGrabPoint)

• Parameters
  • VRTK_InteractableObject currentGrabbdObject – The Interactable Object script for the object currently being grabbed by the primary controller.
  • VRTK_InteractGrab currentPrimaryGrabbingObject – The Interact Grab script for the object that is associated with the primary controller.
  • VRTK_InteractGrab currentSecondaryGrabbingObject – The Interact Grab script for the object that is associated with the secondary controller.
  • Transform primaryGrabPoint – The point on the object where the primary controller initially grabbed the object.
  • Transform secondaryGrabPoint – The point on the object where the secondary controller initially grabbed the object.
• Returns
  • none

The Initalise method is used to set up the state of the secondary action when the object is initially grabbed by a secondary controller.

ProcessUpdate/0

public override void ProcessUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessUpdate method runs in every Update on the Interactable Object whilst it is being grabbed by a secondary controller.

ProcessFixedUpdate/0

public override void ProcessFixedUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessFixedUpdate method runs in every FixedUpdate on the Interactable Object whilst it is being grabbed by a secondary controller and performs the scaling action.

Example

VRTK/Examples/043_Controller_SecondaryControllerActions demonstrates the ability to grab an object with one controller and scale it by grabbing and pulling with the second controller.

---

Control Direction Grab Action (VRTK_ControlDirectionGrabAction)

extends VRTK_BaseGrabAction

Overview

The Control Direction Grab Action provides a mechanism to control the facing direction of the object when they are grabbed with a secondary controller.

For an object to correctly be rotated it must be created with the front of the object pointing down the z-axis (forward) and the upwards of the object pointing up the y-axis (up).

It’s not possible to control the direction of an interactable object with a Fixed_Joint as the joint fixes the rotation of the object.

Inspector Parameters

• Ungrab Distance: The distance the secondary controller must move away from the original grab position before the secondary controller auto ungrabs the object.
• Release Snap Speed: The speed in which the object will snap back to it’s original rotation when the secondary controller stops grabbing it. 0 for instant snap, infinity for no snap back.
• Lock Z Rotation: Prevent the secondary controller rotating the grabbed object through it’s z-axis.

Class Methods

Initialise/5

public override void Initialise(VRTK_InteractableObject currentGrabbdObject, VRTK_InteractGrab currentPrimaryGrabbingObject, VRTK_InteractGrab currentSecondaryGrabbingObject, Transform primaryGrabPoint, Transform secondaryGrabPoint)

• Parameters
  • VRTK_InteractableObject currentGrabbdObject – The Interactable Object script for the object currently being grabbed by the primary controller.
  • VRTK_InteractGrab currentPrimaryGrabbingObject – The Interact Grab script for the object that is associated with the primary controller.
  • VRTK_InteractGrab currentSecondaryGrabbingObject – The Interact Grab script for the object that is associated with the secondary controller.
  • Transform primaryGrabPoint – The point on the object where the primary controller initially grabbed the object.
  • Transform secondaryGrabPoint – The point on the object where the secondary controller initially grabbed the object.
• Returns
  • none

The Initalise method is used to set up the state of the secondary action when the object is initially grabbed by a secondary controller.

ResetAction/0

public override void ResetAction()

• Parameters
  • none
• Returns
  • none

The ResetAction method is used to reset the secondary action when the object is no longer grabbed by a secondary controller.

OnDropAction/0

public override void OnDropAction()

• Parameters
  • none
• Returns
  • none

The OnDropAction method is executed when the current grabbed object is dropped and can be used up to clean up any secondary grab actions.

ProcessUpdate/0

public override void ProcessUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessUpdate method runs in every Update on the Interactable Object whilst it is being grabbed by a secondary controller.

ProcessFixedUpdate/0

public override void ProcessFixedUpdate()

• Parameters
  • none
• Returns
  • none

The ProcessFixedUpdate method runs in every FixedUpdate on the Interactable Object whilst it is being grabbed by a secondary controller and influences the rotation of the object.

Example

VRTK/Examples/043_Controller_SecondaryControllerActions demonstrates the ability to grab an object with one controller and control their direction with the second controller.