VRTK_InteractableObject

Overview

The Interactable Object script is attached to any game object that is required to be interacted with (e.g. via the controllers).

The basis of this script is to provide a simple mechanism for identifying objects in the game world that can be grabbed or used but it is expected that this script is the base to be inherited into a script with richer functionality.

The highlighting of an Interactable Object is defaulted to use the VRTK_MaterialColorSwapHighlighter if no other highlighter is applied to the Object.

Inspector Parameters

• Highlight On Touch: The object will only highlight when a controller touches it if this is checked.
• Touch Highlight Color: The colour to highlight the object when it is touched. This colour will override any globally set colour (for instance on the VRTK_InteractTouch script).
• Rumble On Touch: The haptic feedback on the controller can be triggered upon touching the object, the Strength denotes the strength of the pulse, the Duration denotes the length of time.
• Allowed Touch Controllers: Determines which controller can initiate a touch action.
• Hide Controller On Touch: Optionally override the controller setting.
• Is Grabbable: Determines if the object can be grabbed.
• Is Droppable: Determines if the object can be dropped by the controller grab button being used. If this is unchecked then it's not possible to drop the item once it's picked up using the controller button.
• Is Swappable: Determines if the object can be swapped between controllers when it is picked up. If it is unchecked then the object must be dropped before it can be picked up by the other controller.
• Hold Button To Grab: If this is checked then the grab button on the controller needs to be continually held down to keep grabbing. If this is unchecked the grab button toggles the grab action with one button press to grab and another to release.
• Grab Override Button: If this is set to Undefined then the global grab alias button will grab the object, setting it to any other button will ensure the override button is used to grab this specific interactable object.
• Rumble On Grab: The haptic feedback on the controller can be triggered upon grabbing the object, the Strength denotes the strength of the pulse, the Duration denotes the length of time.
• Allowed Grab Controllers: Determines which controller can initiate a grab action.
• Precision Snap: 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.
• Hide Controller On Grab: Optionally override the controller setting.
• Stay Grabbed On Teleport: If this is checked then the object will stay grabbed to the controller when a teleport occurs. If it is unchecked then the object will be released when a teleport occurs.
• Grab Attach Mechanic: This determines how the grabbed item will be attached to the controller when it is grabbed.
• Detach Threshold: The force amount when to detach the object from the grabbed controller. If the controller tries to exert a force higher than this threshold on the object (from pulling it through another object or pushing it into another object) then the joint holding the object to the grabbing controller will break and the object will no longer be grabbed. This also works with Tracked Object grabbing but determines how far the controller is from the object before breaking the grab. Only required for Fixed Joint, Spring Joint, Track Object and Rotator Track.
• Spring Joint Strength: The strength of the spring holding the object to the controller. A low number will mean the spring is very loose and the object will require more force to move it, a high number will mean a tight spring meaning less force is required to move it. Only required for Spring Joint.
• Spring Joint Damper: The amount to damper the spring effect when using a Spring Joint grab mechanic. A higher number here will reduce the oscillation effect when moving jointed Interactable Objects. Only required for Spring Joint.
• 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.
• Is Usable: Determines if the object can be used.
• Use Only If Grabbed: If this is checked the object can be used only if it is currently being grabbed.
• Hold Button To Use: If this is checked then the use button on the controller needs to be continually held down to keep using. If this is unchecked the the use button toggles the use action with one button press to start using and another to stop using.
• Use Override Button: If this is set to Undefined then the global use alias button will use the object, setting it to any other button will ensure the override button is used to use this specific interactable object.
• Pointer Activates Use Action: If this is checked then when a World Pointer beam (projected from the controller) hits the interactable object, if the object has Hold Button To Use unchecked then whilst the pointer is over the object it will run it's Using method. If Hold Button To Use is unchecked then the Using method will be run when the pointer is deactivated. The world pointer will not throw the Destination Set event if it is affecting an interactable object with this setting checked as this prevents unwanted teleporting from happening when using an object with a pointer.
• Rumble On Use: The haptic feedback on the controller can be triggered upon using the object, the Strength denotes the strength of the pulse, the Duration denotes the length of time.
• Allowed Use Controllers: Determines which controller can initiate a use action.
• Hide Controller On Use: Optionally override the controller setting.

Class Variables

• public enum GrabAttachType - Types of grab attachment.
• Fixed_Joint - Attaches the object to the controller with a fixed joint meaning it tracks the position and rotation of the controller with perfect 1:1 tracking.
• Spring_Joint - Attaches the object to the controller with a spring joint meaning there is some flexibility between the item and the controller force moving the item. This works well when attempting to pull an item rather than snap the item directly to the controller. It creates the illusion that the item has resistance to move it.
• Track_Object - Doesn't attach the object to the controller via a joint, instead it ensures the object tracks the direction of the controller, which works well for items that are on hinged joints.
• Rotator_Track - Tracks 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.
• Child_Of_Controller - Makes the object a child of the controller grabbing so it naturally tracks the position of the controller motion.
• Climbable - Non-rigid body interactable object used to allow player climbing.
• public enum AllowedController - Allowed controller type.
• Both - Both controllers are allowed to interact.
• Left_Only - Only the left controller is allowed to interact.
• Right_Only - Only the right controller is allowed to interact.
• public enum ControllerHideMode - Hide controller state.
• Default - Use the hide settings from the controller.
• OverrideHide - Hide the controller when interacting, overriding controller settings.
• OverrideDontHide - Don't hide the controller when interacting, overriding controller settings.
• public int usingState - The current using state of the object. 0 not being used, 1 being used. Default: 0

Class Events

• InteractableObjectTouched - Emitted when another object touches the current object.
• InteractableObjectUntouched - Emitted when the other object stops touching the current object.
• InteractableObjectGrabbed - Emitted when another object grabs the current object (e.g. a controller).
• InteractableObjectUngrabbed - Emitted when the other object stops grabbing the current object.
• InteractableObjectUsed - Emitted when another object uses the current object (e.g. a controller).
• InteractableObjectUnused - Emitted when the other object stops using the current object.

Unity Events

Adding the VRTK_InteractableObject_UnityEvents component to VRTK_InteractableObject object allows access to UnityEvents that will react identically to the Class Events.

• OnTouch - Emits the InteractableObjectTouched class event.
• OnUntouch - Emits the InteractableObjectUntouched class event.
• OnGrab - Emits the InteractableObjectGrabbed class event.
• OnUngrab - Emits the InteractableObjectUngrabbed class event.
• OnUse - Emits the InteractableObjectUsed class event.
• OnUnuse - Emits the InteractableObjectUnused class event.

Event Payload

• GameObject interactingObject - The object that is initiating the interaction (e.g. a controller).

Class Methods

CheckHideMode/2

public bool CheckHideMode(bool defaultMode, ControllerHideMode overrideMode)

• Parameters
• bool defaultMode - The default setting of the controller. true = hide, false = don't hide.
• ControllerHideMode overrideMode - The override setting of the object.
• Returns
• bool - Returns true if the combination of defaultMode and overrideMode lead to "hide controller.

The CheckHideMode method is a simple service method used only by some scripts (e.g. InteractTouch InteractGrab InteractUse) to calculate the "hide controller" condition according to the default controller settings and the interactive object override method.

IsTouched/0

public bool IsTouched()

• Parameters
• none
• Returns
• bool - Returns true if the object is currently being touched.

The IsTouched method is used to determine if the object is currently being touched.

IsGrabbed/0

public bool IsGrabbed()

• Parameters
• none
• Returns
• bool - Returns true if the object is currently being grabbed.

The IsGrabbed method is used to determine if the object is currently being grabbed.

IsUsing/0

public bool IsUsing()

• Parameters
• none
• Returns
• bool - Returns true if the object is currently being used.

The IsUsing method is used to determine if the object is currently being used.

StartTouching/1

public virtual void StartTouching(GameObject currentTouchingObject)

• Parameters
• GameObject currentTouchingObject - The game object that is currently touching this object.
• Returns
• none

The StartTouching method is called automatically when the object is touched initially. It is also a virtual method to allow for overriding in inherited classes.

StopTouching/1

public virtual void StopTouching(GameObject previousTouchingObject)

• Parameters
• GameObject previousTouchingObject - The game object that was previously touching this object.
• Returns
• none

The StopTouching method is called automatically when the object has stopped being touched. It is also a virtual method to allow for overriding in inherited classes.

Grabbed/1

public virtual void Grabbed(GameObject currentGrabbingObject)

• Parameters
• GameObject currentGrabbingObject - The game object that is currently grabbing this object.
• Returns
• none

The Grabbed method is called automatically when the object is grabbed initially. It is also a virtual method to allow for overriding in inherited classes.

Ungrabbed/1

public virtual void Ungrabbed(GameObject previousGrabbingObject)

• Parameters
• GameObject previousGrabbingObject - The game object that was previously grabbing this object.
• Returns
• none

The Ungrabbed method is called automatically when the object has stopped being grabbed. It is also a virtual method to allow for overriding in inherited classes.

StartUsing/1

public virtual void StartUsing(GameObject currentUsingObject)

• Parameters
• GameObject currentUsingObject - The game object that is currently using this object.
• Returns
• none

The StartUsing method is called automatically when the object is used initially. It is also a virtual method to allow for overriding in inherited classes.

StopUsing/1

public virtual void StopUsing(GameObject previousUsingObject)

• Parameters
• GameObject previousUsingObject - The game object that was previously using this object.
• Returns
• none

The StopUsing method is called automatically when the object has stopped being used. It is also a virtual method to allow for overriding in inherited classes.

ToggleHighlight/1

public virtual void ToggleHighlight(bool toggle)

• Parameters
• bool toggle - The state to determine whether to activate or deactivate the highlight. true will enable the highlight and false will remove the highlight.
• Returns
• none

The ToggleHighlight/1 method is used as a shortcut to disable highlights whilst keeping the same method signature. It should always be used with false and it calls ToggleHighlight/2 with a Color.clear.

ToggleHighlight/2

public virtual void ToggleHighlight(bool toggle, Color globalHighlightColor)

• Parameters
• bool toggle - The state to determine whether to activate or deactivate the highlight. true will enable the highlight and false will remove the highlight.
• Color globalHighlightColor - The colour to use when highlighting the object.
• Returns
• none

The ToggleHighlight/2 method is used to turn on or off the colour highlight of the object.

PauseCollisions/0

public void PauseCollisions()

• Parameters
• none
• Returns
• none

The PauseCollisions method temporarily pauses all collisions on the object at grab time by removing the object's rigidbody's ability to detect collisions. This can be useful for preventing clipping when initially grabbing an item.

AttachIsTrackObject/0

public bool AttachIsTrackObject()

• Parameters
• none
• Returns
• bool - Is true if the grab attach mechanic is one of the track types like Track Object or Rotator Track.

The AttachIsTrackObject method is used to determine if the object is using one of the track grab attach mechanics.

AttachIsClimbObject/0

public bool AttachIsClimbObject()

• Parameters
• none
• Returns
• bool - Is true if the grab attach mechanic is Climbable.

The AttachIsClimbObject method is used to determine if the object is using the Climbable grab attach mechanics.

AttachIsKinematicObject/0

public bool AttachIsKinematicObject()

• Parameters
• none
• Returns
• bool - Is true if the grab attach mechanic sets the object to a kinematic state on grab.

The AttachIsKinematicObject method is used to determine if the object has kinematics turned on at the point of grab.

AttachIsStaticObject/0

public bool AttachIsStaticObject()

• Parameters
• none
• Returns
• bool - Is true if the grab attach mechanic is one of the static types like Climbable.

The AttachIsStaticObject method is used to determine if the object is using one of the static grab attach types.

AttachIsUnthrowableObject/0

public bool AttachIsUnthrowableObject()

• Parameters
• none
• Returns
• bool - Is true if the grab attach mechanic is of a type that shouldn't be considered thrown when released.

The AttachIsUnthrowableObject method is used to determine if the object is using one of the grab types that should not be thrown when released.

ZeroVelocity/0

public void ZeroVelocity()

• Parameters
• none
• Returns
• none

The ZeroVelocity method resets the velocity and angular velocity to zero on the rigidbody attached to the object.

SaveCurrentState/0

public void SaveCurrentState()

• Parameters
• none
• Returns
• none

The SaveCurrentState method stores the existing object parent and the object's rigidbody kinematic setting.

ToggleKinematic/1

public void ToggleKinematic(bool state)

• Parameters
• bool state - The object's rigidbody kinematic state.
• Returns
• none

The ToggleKinematic method is used to set the object's internal rigidbody kinematic state.

GetGrabbingObject/0

public GameObject GetGrabbingObject()

• Parameters
• none
• Returns
• GameObject - The game object of what is grabbing the current object.

The GetGrabbingObject method is used to return the game object that is currently grabbing this object.

IsValidInteractableController/2

public bool IsValidInteractableController(GameObject actualController, AllowedController controllerCheck)

• Parameters
• GameObject actualController - The game object of the controller that is being checked.
• AllowedController controllerCheck - The value of which controller is allowed to interact with this object.
• Returns
• bool - Is true if the interacting controller is allowed to grab the object.

The IsValidInteractableController method is used to check to see if a controller is allowed to perform an interaction with this object as sometimes controllers are prohibited from grabbing or using an object depedning on the use case.

ForceStopInteracting/0

public void ForceStopInteracting()

• Parameters
• none
• Returns
• none

The ForceStopInteracting method forces the object to no longer be interacted with and will cause a controller to drop the object and stop touching it. This is useful if the controller is required to auto interact with another object.

SetGrabbedSnapHandle/1

public void SetGrabbedSnapHandle(Transform handle)

• Parameters
• Transform handle - A transform of an object to use for the snap handle when the object is grabbed.
• Returns
• none

The SetGrabbedSnapHandle method is used to set the snap handle of the object at runtime.

RegisterTeleporters/0

public void RegisterTeleporters()

• Parameters
• none
• Returns
• none

The RegisterTeleporters method is used to find all objects that have a teleporter script and register the object on the OnTeleported event. This is used internally by the object for keeping Tracked objects positions updated after teleporting.

Example

VRTK/Examples/005_Controller_BasicObjectGrabbing uses the VRTK_InteractTouch and VRTK_InteractGrab scripts on the controllers to show how an interactable object can be grabbed and snapped to the controller and thrown around the game world.

VRTK/Examples/013_Controller_UsingAndGrabbingMultipleObjects shows multiple objects that can be grabbed by holding the buttons or grabbed by toggling the button click and also has objects that can have their Using state toggled to show how multiple items can be turned on at the same time.