VRTK_InteractableObject

Overview

Determines if the GameObject can be interacted with.

Required Components:

• Collider - A Unity Collider to determine when an interaction has occured. Can be a compound collider set in child GameObjects.

Optional Components:

• Rigidbody - A Unity Rigidbody to allow the GameObject to be affected by the Unity Physics System (not required for Climbable Grab Attach Types).
• VRTK_BaseGrabAttach - A Grab Attach mechanic for determining how the Interactable Object is grabbed by the primary interacting object.
• VRTK_BaseGrabAction - A Grab Action mechanic for determining how to manipulate the Interactable Object when grabbed by the secondary interacting object.

Script Usage:

• Place the VRTK_InteractableObject script onto the GameObject that is to be interactable.
• Alternatively, select the GameObject and use the Window -> VRTK -> Setup Interactable Object panel to set up quickly.
• The optional Highlighter used by the Interactable Object will be selected in the following order:
  • The provided Base Highlighter in the Object Highlighter parameter.
  • If the above is not provided, then the first active Base Highlighter found on the Interactable Object GameObject will be used.
  • If the above is not found, then a Material Color Swap Highlighter will be created on the Interactable Object GameObject at runtime.

Script Dependencies:

• Interactions
  • To near touch an Interactable Object the Interact NearTouch script is required on a controller Script Alias GameObject.
  • To touch an Interactable Object the Interact NearTouch script is required on a controller Script Alias GameObject.
  • To grab an Interactable Object the Interact Grab script is required on a controller Script Alias GameObject.
  • To use an Interactable Object the Interact Use script is required on a controller Script Alias GameObject.
• Highlighting
  • To highlight an Interactable Object on a given interaction then a valid Interact Object Highlighter script must be associated with the Interactable Object.
• Appearance
  • To affect the appearance of an Interactable Object then a valid Interact Object Appearance script must be associated with the Interactable Object.

Inspector Parameters

• Disable When Idle: If this is checked then the Interactable Object component will be disabled when the Interactable Object is not being interacted with.
• Allowed Near Touch Controllers: Determines which controller can initiate a near touch action.
• Allowed Touch Controllers: Determines which controller can initiate a touch action.
• Ignored Colliders: An array of colliders on the GameObject to ignore when being touched.
• Is Grabbable: Determines if the Interactable 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 Interactable Object will stay grabbed to the controller when a teleport occurs. If it is unchecked then the Interactable Object will be released when a teleport occurs.
• Valid Drop: Determines in what situation the Interactable Object can be dropped by the controller grab button.
• Grab Override Button: Setting to a button will ensure the override button is used to grab this specific Interactable Object. Setting to Undefined will mean the Grab Button on the Interact Grab script will grab the object.
• Allowed Grab Controllers: Determines which controller can initiate a grab action.
• Grab Attach Mechanic Script: This determines how the grabbed Interactable Object 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 Interactable 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 Interactable Object can be used only if it is currently being grabbed.
• Pointer Activates Use Action: If this is checked then when a Pointer collides with the Interactable Object it will activate it's use action. If the the Hold Button To Use parameter is unchecked then whilst the Pointer is collising with the Interactable Object it will run the Using method. If Hold Button To Use is unchecked then the Using method will be run when the Pointer is deactivated. The Pointer will not emit 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 Interactable Object with a pointer.
• Use Override Button: Setting to a button will ensure the override button is used to use this specific Interactable Object. Setting to Undefined will mean the Use Button on the Interact Use script will use the object.
• Allowed Use Controllers: Determines which controller can initiate a use action.

Class Variables

• public enum InteractionType - The interaction type.
  • None - No interaction is affecting the object.
  • NearTouch - The near touch interaction is affecting the object.
  • NearUntouch - The near untouch interaction stopped affecting the object
  • Touch - The touch interaction is affecting the object.
  • Untouch - The untouch interaction stopped affecting the object
  • Grab - The grab interaction is affecting the object.
  • Ungrab - The ungrab interaction stopped affecting the object
  • Use - The use interaction is affecting the object.
  • Unuse - The unuse interaction stopped affecting the object
• public enum AllowedController - Allowed controller type.
  • Both - Both controllers are allowed to interact.
  • LeftOnly - Only the left controller is allowed to interact.
  • RightOnly - Only the right controller is allowed to interact.
• public enum ValidDropTypes - The types of valid situations that the object can be released from grab.
  • NoDrop - The object cannot be dropped via the controller.
  • DropAnywhere - The object can be dropped anywhere in the scene via the controller.
  • DropValidSnapDropZone - 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 Interactable 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 Interactable Object's Rigidbody component.

Class Events

• InteractableObjectEnabled - Emitted when the Interactable Object script is enabled;
• InteractableObjectDisabled - Emitted when the Interactable Object script is disabled;
• InteractableObjectNearTouched - Emitted when another interacting object near touches the current Interactable Object.
• InteractableObjectNearUntouched - Emitted when the other interacting object stops near touching the current Interactable Object.
• InteractableObjectTouched - Emitted when another interacting object touches the current Interactable Object.
• InteractableObjectUntouched - Emitted when the other interacting object stops touching the current Interactable Object.
• InteractableObjectGrabbed - Emitted when another interacting object grabs the current Interactable Object.
• InteractableObjectUngrabbed - Emitted when the other interacting object stops grabbing the current Interactable Object.
• InteractableObjectUsed - Emitted when another interacting object uses the current Interactable Object.
• InteractableObjectUnused - Emitted when the other interacting object stops using the current Interactable Object.
• InteractableObjectEnteredSnapDropZone - Emitted when the Interactable Object enters a Snap Drop Zone.
• InteractableObjectExitedSnapDropZone - Emitted when the Interactable Object exists a Snap Drop Zone.
• InteractableObjectSnappedToDropZone - Emitted when the Interactable Object gets snapped to a Snap Drop Zone.
• InteractableObjectUnsnappedFromDropZone - Emitted when the Interactable Object gets unsnapped from a Snap Drop Zone.

Unity Events

Adding the VRTK_InteractableObject_UnityEvents component to VRTK_InteractableObject 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 initiating the interaction (e.g. a controller).

Class Methods

IsNearTouched/0

public virtual bool IsNearTouched()

• Parameters
  • none
• Returns
  • bool - Returns true if the Interactable Object is currently being near touched.

The IsNearTouched method is used to determine if the Interactable Object is currently being near touched.

IsTouched/0

public virtual bool IsTouched()

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

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

IsGrabbed/1

public virtual 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 Interactable Object is currently being grabbed.

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

IsUsing/1

public virtual 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 Interactable Object is currently being used.

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

StartNearTouching/1

public virtual void StartNearTouching(VRTK_InteractNearTouch currentNearTouchingObject = null)

• Parameters
  • VRTK_InteractNearTouch currentNearTouchingObject - The interacting object that is currently nearly touching this Interactable Object.
• Returns
  • none

The StartNearTouching method is called automatically when the Interactable Object is initially nearly touched.

StopNearTouching/1

public virtual void StopNearTouching(VRTK_InteractNearTouch previousNearTouchingObject = null)

• Parameters
  • VRTK_InteractNearTouch previousNearTouchingObject - The interacting object that was previously nearly touching this Interactable Object.
• Returns
  • none

The StopNearTouching method is called automatically when the Interactable Object has stopped being nearly touched.

StartTouching/1

public virtual void StartTouching(VRTK_InteractTouch currentTouchingObject = null)

• Parameters
  • VRTK_InteractTouch currentTouchingObject - The interacting object that is currently touching this Interactable Object.
• Returns
  • none

The StartTouching method is called automatically when the Interactable Object is touched initially.

StopTouching/1

public virtual void StopTouching(VRTK_InteractTouch previousTouchingObject = null)

• Parameters
  • VRTK_InteractTouch previousTouchingObject - The interacting object that was previously touching this Interactable Object.
• Returns
  • none

The StopTouching method is called automatically when the Interactable Object has stopped being touched.

Grabbed/1

public virtual void Grabbed(VRTK_InteractGrab currentGrabbingObject = null)

• Parameters
  • VRTK_InteractGrab currentGrabbingObject - The interacting object that is currently grabbing this Interactable Object.
• Returns
  • none

The Grabbed method is called automatically when the Interactable Object is grabbed initially.

Ungrabbed/1

public virtual void Ungrabbed(VRTK_InteractGrab previousGrabbingObject = null)

• Parameters
  • VRTK_InteractGrab previousGrabbingObject - The interacting object that was previously grabbing this Interactable Object.
• Returns
  • none

The Ungrabbed method is called automatically when the Interactable Object has stopped being grabbed.

StartUsing/1

public virtual void StartUsing(VRTK_InteractUse currentUsingObject = null)

• Parameters
  • VRTK_InteractUse currentUsingObject - The interacting object that is currently using this Interactable Object.
• Returns
  • none

The StartUsing method is called automatically when the Interactable Object is used initially.

StopUsing/2

public virtual void StopUsing(VRTK_InteractUse previousUsingObject = null, bool resetUsingObjectState = true)

• Parameters
  • VRTK_InteractUse previousUsingObject - The interacting object that was previously using this Interactable Object.
  • bool resetUsingObjectState - Resets the using object state to reset it's using action.
• Returns
  • none

The StopUsing method is called automatically when the Interactable Object has stopped being used.

PauseCollisions/1

public virtual void PauseCollisions(float delay)

• Parameters
  • float delay - The time in seconds to pause the collisions for.
• Returns
  • none

The PauseCollisions method temporarily pauses all collisions on the Interactable Object at grab time by removing the Interactable Object's Rigidbody's ability to detect collisions.

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 Interactable Object.

SaveCurrentState/0

public virtual void SaveCurrentState()

• Parameters
  • none
• Returns
  • none

The SaveCurrentState method stores the existing Interactable Object parent and the Rigidbody kinematic setting.

GetPreviousState/3

public virtual void GetPreviousState(out Transform previousParent, out bool previousKinematic, out bool previousGrabbable)

• Parameters
  • out Transform previousParent - Out param for the previous parent
  • out bool previousKinematic - Out param for the previous Kinematic state
  • out bool previousGrabbable - Out param for the previous Grabbable State
• Returns
  • none

Returns the previous state of the Interactable Object

OverridePreviousState/3

public virtual void OverridePreviousState(Transform previousParent, bool previousKinematic, bool previousGrabbable)

• Parameters
  • Transform previousParent - value of the previous parent
  • bool previousKinematic - value of the previous Kinematic state
  • bool previousGrabbable - value of the previous Grabbable State
• Returns
  • none

Overrides the previous state of the Interactable Object

GetNearTouchingObjects/0

public virtual List<GameObject> GetNearTouchingObjects()

• Parameters
  • none
• Returns
  • List<GameObject> - A list of GameObject of that are currently nearly touching the current Interactable Object.

The GetNearTouchingObjects method is used to return the collecetion of valid GameObjects that are currently nearly touching this Interactable Object.

GetTouchingObjects/0

public virtual List<GameObject> GetTouchingObjects()

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

The GetTouchingObjects method is used to return the collecetion of valid GameObjects that are currently touching this Interactable Object.

GetGrabbingObject/0

public virtual GameObject GetGrabbingObject()

• Parameters
  • none
• Returns
  • GameObject - The GameObject of what is grabbing the current Interactable Object.

The GetGrabbingObject method is used to return the GameObject that is currently grabbing this Interactable Object.

GetSecondaryGrabbingObject/0

public virtual GameObject GetSecondaryGrabbingObject()

• Parameters
  • none
• Returns
  • GameObject - The GameObject of the secondary influencing object of the current grabbed Interactable Object.

The GetSecondaryGrabbingObject method is used to return the GameObject that is currently being used to influence this Interactable Object whilst it is being grabbed by a secondary influencing.

GetUsingObject/0

public virtual GameObject GetUsingObject()

• Parameters
  • none
• Returns
  • GameObject - The GameObject of what is using the current Interactable Object.

The GetUsingObject method is used to return the GameObject that is currently using this Interactable Object.

GetUsingScript/0

public virtual VRTK_InteractUse GetUsingScript()

• Parameters
  • none
• Returns
  • VRTK_InteractUse - The Interact Use script of the interacting object that is using the current Interactable Object.

The GetUsingScript method is used to return the Interact Use component that is currently using this Interactable Object.

IsValidInteractableController/2

public virtual bool IsValidInteractableController(GameObject actualController, AllowedController controllerCheck)

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

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

ForceStopInteracting/0

public virtual void ForceStopInteracting()

• Parameters
  • none
• Returns
  • none

The ForceStopInteracting method forces the Interactable Object to no longer be interacted with and will cause an interacting object to drop the Interactable Object and stop touching it.

ForceStopSecondaryGrabInteraction/0

public virtual void ForceStopSecondaryGrabInteraction()

• Parameters
  • none
• Returns
  • none

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

RegisterTeleporters/0

public virtual void RegisterTeleporters()

• Parameters
  • none
• Returns
  • none

The RegisterTeleporters method is used to find all GameObjects that have a teleporter script and register the Interactable Object on the OnTeleported event.

UnregisterTeleporters/0

public virtual void UnregisterTeleporters()

• Parameters
  • none
• Returns
  • none

The UnregisterTeleporters method is used to unregister all teleporter events that are active on this Interactable 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 snapped 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 virtual bool IsInSnapDropZone()

• Parameters
  • none
• Returns
  • bool - Returns true if the Interactable Object is currently snapped in a Snap Drop Zone, returns false if it is not.

The IsInSnapDropZone method determines whether the Interactable Object is currently snapped to a Snap Drop Zone.

SetSnapDropZoneHover/2

public virtual void SetSnapDropZoneHover(VRTK_SnapDropZone snapDropZone, bool state)

• Parameters
  • VRTK_SnapDropZone snapDropZone - The Snap Drop Zone that is being interacted with.
  • bool state - The state of whether the Interactable 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 virtual 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.

IsHoveredOverSnapDropZone/0

public virtual bool IsHoveredOverSnapDropZone()

• Parameters
  • none
• Returns
  • bool - Returns true if the Interactable Object is currently hovering over a Snap Drop Zone.

The IsHoveredOverSnapDropZone method returns whether the Interactable Object is currently hovering over a Snap Drop Zone.

IsDroppable/0

public virtual bool IsDroppable()

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

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

IsSwappable/0

public virtual bool IsSwappable()

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

The IsSwappable method returns whether the Interactable Object can be grabbed with one interacting object and then swapped to another interacting object by grabbing with the secondary grab action.

PerformSecondaryAction/0

public virtual bool PerformSecondaryAction()

• Parameters
  • none
• Returns
  • bool - Returns true if the Interactable Object has a Secondary Grab Action, returns false if it has no Secondary Grab Action or is swappable.

The PerformSecondaryAction method returns whether the Interactable Object has a Secondary Grab Action that can be performed when grabbing the object with a secondary interacting object.

ResetIgnoredColliders/0

public virtual void ResetIgnoredColliders()

• Parameters
  • none
• Returns
  • none

The ResetIgnoredColliders method is used to clear any stored ignored colliders in case the Ignored Colliders array parameter is changed at runtime. This needs to be called manually if changes are made at runtime.

SubscribeToInteractionEvent/2

public virtual void SubscribeToInteractionEvent(InteractionType givenType, InteractableObjectEventHandler methodCallback)

• Parameters
  • InteractionType givenType - The Interaction Type to register the events for.
  • InteractableObjectEventHandler methodCallback - The method to execute when the Interaction Type is initiated.
• Returns
  • none

The SubscribeToInteractionEvent method subscribes a given method callback for the given Interaction Type.

UnsubscribeFromInteractionEvent/2

public virtual void UnsubscribeFromInteractionEvent(InteractionType givenType, InteractableObjectEventHandler methodCallback)

• Parameters
  • InteractionType givenType - The Interaction Type that the previous event subscription was under.
  • InteractableObjectEventHandler methodCallback - The method that was being executed when the Interaction Type was initiated.
• Returns
  • none

The UnsubscribeFromInteractionEvent method unsubscribes a previous event subscription for the given Interaction Type.

GetPrimaryAttachPoint/0

public virtual Transform GetPrimaryAttachPoint()

• Parameters
  • none
• Returns
  • Transform - A Transform that denotes where the primary grabbing object is grabbing the Interactable Object at.

The GetPrimaryAttachPoint returns the Transform that determines where the primary grabbing object is grabbing the Interactable Object at.

GetSecondaryAttachPoint/0

public virtual Transform GetSecondaryAttachPoint()

• Parameters
  • none
• Returns
  • Transform - A Transform that denotes where the secondary grabbing object is grabbing the Interactable Object at.

The GetSecondaryAttachPoint returns the Transform that determines where the secondary grabbing object is grabbing the Interactable Object at.

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.