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.

Inspector Parameters

Touch Interactions

• 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 color (for instance on the VRTK_InteractTouch script).
• Rumble On Touch: The haptic feedback on the controller can be triggered upon touching the object, the x denotes the length of time, the y denotes the strength of the pulse. (x and y will be replaced in the future with a custom editor)
• Allowed Touch Controllers: Determines which controller can initiate a touch action. The options available are:
• Both means both controllers will register a touch.
• Left_Only means only the left controller will register a touch.
• Right_Only means only the right controller will register a touch.
• Hide Controller On Touch: Optionally override the controller setting (hide when touched):
• Default means using controller settings.
• Override Hide means hiding the controller when touched, overriding controller settings.
• Override Dont Hide means not hiding the controller when touched, overriding controller settings.

Grab Interactions

• 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. It is still possible for the item to be dropped if the Grab Attach Mechanic is a joint and too much force is applied to the object and the joint is broken. To prevent this it's better to use the Child Of Controller mechanic.
• 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.
• Rumble On Grab: The haptic feedback on the controller can be triggered upon grabbing the object, the x denotes the length of time, the y denotes the strength of the pulse. (x and y will be replaced in the future with a custom editor).
• Allowed Grab Controllers: Determines which controller can initiate a grab action. The options available are:
• Both means both controllers are allowed to grab.
• Left_Only means only the left controller is allowed to grab.
• Right_Only means only the right controller is allowed to grab.
• 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 it's central point.
• 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 it's central point.
• Hide Controller On Grab: Optionally override the controller setting (hide when grabbed):
• Default means using controller settings.
• Override Hide means hiding the controller when grabbed, overriding controller settings.
• Override Dont Hide means not hiding the controller when grabbed, overriding controller settings.

Grab Mechanics

• Grab Attach Type: This determines how the grabbed item will be attached to the controller when it is grabbed.
• 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 also 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 simply 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.
• 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.
• 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.
• 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.
• 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.

Use Interactions

• 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 was grabbed before.
• 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.
• 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 x denotes the length of time, the y denotes the strength of the pulse. (x and y will be replaced in the future with a custom editor).
• Allowed Use Controllers: Determines which controller can initiate a use action. The options available are:
• Both means both controllers are allowed to use.
• Left_Only means only the left controller is allowed to use.
• Right_Only means only the right controller is allowed to use.
• Hide Controller On Use: Optionally override the controller setting (hide when used):
• Default means using controller settings.
• Override Hide means hiding the controller when using, overriding controller settings.
• Override Dont Hide means not hiding the controller when using, overriding controller settings.

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.

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.
  • Default means using controller settings (returns overrideMode).
  • OverrideHide means hiding the controller anyway (even if defaultModeis true).
  • OverrideDontHide means not hiding the controller anyway (even if defaultModeis false).
• 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.

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.

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

SteamVR_Unity_Toolkit/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.

SteamVR_Unity_Toolkit/Examples/013_Controller_UsingAndGrabbingMultipleObjects shows mutltiple 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 mutliple items can be turned on at the same time.