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

• Disable When Idle: If this is checked then the interactable object script will be disabled when the object is not being interacted with. This will eliminate the potential number of calls the interactable objects make each frame.
• 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).
• Allowed Touch Controllers: Determines which controller can initiate a touch action.
• Is Grabbable: Determines if the object can be grabbed.
• 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.
• 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.
• Valid Drop: Determines in what situation the object can be dropped by the controller grab button.
• 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.
• Allowed Grab Controllers: Determines which controller can initiate a grab action.
• Grab Attach Mechanic Script: This determines how the grabbed item will be attached to the controller when it is grabbed. If one isn't provided then the first Grab Attach script on the GameObject will be used, if one is not found and the object is grabbable then a Fixed Joint Grab Attach script will be created at runtime.
• Secondary Grab Action Script: The script to utilise when processing the secondary controller action on a secondary grab attempt. If one isn't provided then the first Secondary Controller Grab Action script on the GameObject will be used, if one is not found then no action will be taken on secondary grab.
• Is Usable: Determines if the object can be used.
• 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 Only If Grabbed: If this is checked the object can be used only if it is currently being grabbed.
• Pointer Activates Use Action: If this is checked then when a Base 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.
• 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.
• Allowed Use Controllers: Determines which controller can initiate a use action.

Class Variables

• 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 ValidDropTypes - The types of valid situations that the object can be released from grab.
• No_Drop - The object cannot be dropped via the controller
• Drop_Anywhere - The object can be dropped anywhere in the scene via the controller.
• Drop_ValidSnapDropZone - The object can only be dropped when it is hovering over a valid snap drop zone.
• public int usingState - The current using state of the object. 0 not being used, 1 being used. Default: 0
• public bool isKinematic - isKinematic is a pass through to the isKinematic getter/setter on the object's rigidbody component.

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

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/1

public bool IsGrabbed(GameObject grabbedBy = null)

• Parameters
• GameObject grabbedBy - An optional GameObject to check if the Interactable Object is grabbed by that specific GameObject. Defaults to null
• 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/1

public bool IsUsing(GameObject usedBy = null)

• Parameters
• GameObject usedBy - An optional GameObject to check if the Interactable Object is used by that specific GameObject. Defaults to null
• 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 method is used to turn on or off the colour highlight of the object.

ResetHighlighter/0

public virtual void ResetHighlighter()

• Parameters
• none
• Returns
• none

The ResetHighlighter method is used to reset the currently attached highlighter.

PauseCollisions/1

public virtual void PauseCollisions(float delay)

• Parameters
• float delay - The amount of time to pause the collisions for.
• 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.

ZeroVelocity/0

public virtual 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 virtual void SaveCurrentState()

• Parameters
• none
• Returns
• none

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

GetTouchingObjects/0

public List<GameObject> GetTouchingObjects()

• Parameters
• none
• Returns
• List<GameObject> - A list of game object of that are currently touching the current object.

The GetTouchingObjects method is used to return the collecetion of valid game objects that are currently touching this object.

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.

GetSecondaryGrabbingObject/0

public GameObject GetSecondaryGrabbingObject()

• Parameters
• none
• Returns
• GameObject - The game object of the secondary controller influencing the current grabbed object.

The GetSecondaryGrabbingObject method is used to return the game object that is currently being used to influence this object whilst it is being grabbed by a secondary controller.

GetUsingObject/0

public GameObject GetUsingObject()

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

The GetUsingObject method is used to return the game object that is currently using this object.

IsValidInteractableController/2

public virtual 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 virtual 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.

ForceStopSecondaryGrabInteraction/0

public virtual void ForceStopSecondaryGrabInteraction()

• Parameters
• none
• Returns
• none

The ForceStopSecondaryGrabInteraction method forces the object to no longer be influenced by the second controller grabbing it.

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.

UnregisterTeleporters/0

public void UnregisterTeleporters()

• Parameters
• none
• Returns
• none

The UnregisterTeleporters method is used to unregister all teleporter events that are active on this object.

StoreLocalScale/0

public virtual void StoreLocalScale()

• Parameters
• none
• Returns
• none

the StoreLocalScale method saves the current transform local scale values.

ToggleSnapDropZone/2

public virtual void ToggleSnapDropZone(VRTK_SnapDropZone snapDropZone, bool state)

• Parameters
• VRTK_SnapDropZone snapDropZone - The Snap Drop Zone object that is being interacted with.
• bool state - The state of whether the interactable object is fixed in or removed from the Snap Drop Zone. True denotes the interactable object is fixed to the Snap Drop Zone and false denotes it has been removed from the Snap Drop Zone.
• Returns
• none

The ToggleSnapDropZone method is used to set the state of whether the interactable object is in a Snap Drop Zone or not.

IsInSnapDropZone/0

public bool IsInSnapDropZone()

• Parameters
• none
• Returns
• bool - Returns true if the interactable object is currently snapped in a drop zone and returns false if it is not.

The IsInSnapDropZone method determines whether the interactable object is currently snapped to a drop zone.

SetSnapDropZoneHover/1

public void SetSnapDropZoneHover(bool state)

• Parameters
• bool state - The state of whether the object is being hovered or not.
• Returns
• none

The SetSnapDropZoneHover method sets whether the interactable object is currently being hovered over a valid Snap Drop Zone.

GetStoredSnapDropZone/0

public VRTK_SnapDropZone GetStoredSnapDropZone()

• Parameters
• none
• Returns
• VRTK_SnapDropZone - The SnapDropZone that the interactable object is currently snapped to.

The GetStoredSnapDropZone method returns the snap drop zone that the interactable object is currently snapped to.

IsDroppable/0

public bool IsDroppable()

• Parameters
• none
• Returns
• bool - Returns true if the object can currently be dropped and returns false if it is not currently possible to drop.

The IsDroppable method returns whether the object can be dropped or not in it's current situation.

IsSwappable/0

public bool IsSwappable()

• Parameters
• none
• Returns
• bool - Returns true if the object can be grabbed by a secondary controller whilst already being grabbed and the object will swap controllers. Returns false if the object cannot be swapped.

The IsSwappable method returns whether the object can be grabbed with one controller and then swapped to another controller by grabbing with the secondary controller.

PerformSecondaryAction/0

public bool PerformSecondaryAction()

• Parameters
• none
• Returns
• bool - Returns true if the obejct has a secondary action, returns false if it has no secondary action or is swappable.

The PerformSecondaryAction method returns whether the object has a secondary action that can be performed when grabbing the object with a secondary controller.

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.