Class XRGrabInteractable

Interactable component that allows for basic grab functionality. When this behavior is selected (grabbed) by an Interactor, this behavior will follow it around and inherit velocity when released.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
XRBaseInteractable
XRGrabInteractable
Inherited Members
UnityEngine.Object.FindObjectsOfType<T>(System.Boolean)
UnityEngine.Object.FindObjectOfType<T>(System.Boolean)
Namespace: UnityEngine.XR.Interaction.Toolkit
Syntax
[SelectionBase]
[DisallowMultipleComponent]
[RequireComponent(typeof(Rigidbody))]
[AddComponentMenu("XR/XR Grab Interactable", 11)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.2/api/UnityEngine.XR.Interaction.Toolkit.XRGrabInteractable.html")]
public class XRGrabInteractable : XRBaseInteractable, IXRActivateInteractable, IXRHoverInteractable, IXRSelectInteractable, IXRInteractable
Remarks

This behavior is responsible for applying the position, rotation, and local scale calculated by one or more IXRGrabTransformer implementations. A default set of grab transformers are automatically added by Unity, but this functionality can be disabled to manually set those used by this behavior, allowing you to customize where this component should move and rotate to.

Grab transformers are classified into two different types: Single and Multiple. Those added to the Single Grab Transformers list are used when there is a single interactor selecting this object. Those added to the Multiple Grab Transformers list are used when there are multiple interactors selecting this object. You can add multiple grab transformers in a category and they will each be processed in sequence. The Multiple Grab Transformers are given first opportunity to process when there are multiple grabs, and the Single Grab Transformer processing will be skipped if a Multiple Grab Transformer can process in that case.

There are fallback rules that could allow a Single Grab Transformer to be processed when there are multiple grabs, and for a Multiple Grab Transformer to be processed when there is a single grab (though a grab transformer will never be processed if its canProcess returns false).

  • When there is a single interactor selecting this object, the Multiple Grab Transformer will be processed only if the Single Grab Transformer list is empty or if all transformers in the Single Grab Transformer list return false during processing.
  • When there are multiple interactors selecting this object, the Single Grab Transformer will be processed only if the Multiple Grab Transformer list is empty or if all transformers in the Multiple Grab Transformer list return false during processing.

Properties

addDefaultGrabTransformers

Whether Unity will add the default set of grab transformers if either the Single or Multiple Grab Transformers lists are empty.

Declaration
public bool addDefaultGrabTransformers { get; set; }
Property Value
Type Description
Boolean
Remarks

Set this to false if you want to manually set the grab transformers used by populating startingSingleGrabTransformers and startingMultipleGrabTransformers.

See Also

angularVelocityDamping

Scale factor of how much Unity dampens the existing angular velocity when tracking the rotation of the Interactor. The smaller the value, the longer it takes for the angular velocity to decay.

Declaration
public float angularVelocityDamping { get; set; }
Property Value
Type Description
Single
Remarks

Only applies when in VelocityTracking mode.

See Also

angularVelocityScale

Scale factor Unity applies to the tracked angular velocity while updating the Rigidbody when tracking the rotation of the Interactor.

Declaration
public float angularVelocityScale { get; set; }
Property Value
Type Description
Single
Remarks

Only applies when in VelocityTracking mode.

See Also

attachEaseInTime

Time in seconds Unity eases in the attach when selected (a value of 0 indicates no easing).

Declaration
public float attachEaseInTime { get; set; }
Property Value
Type Description
Single

attachPointCompatibilityMode

Controls the method used when calculating the target position of the object. Use Default for consistent attach points between all XRBaseInteractable.MovementType values. Marked for deprecation, this property will be removed in a future version.

Declaration
public XRGrabInteractable.AttachPointCompatibilityMode attachPointCompatibilityMode { get; set; }
Property Value
Type Description
XRGrabInteractable.AttachPointCompatibilityMode
Remarks

This is a backwards compatibility option in order to keep the old, incorrect method of calculating the attach point. Projects that already accounted for the difference can use the Legacy option to maintain the same attach positioning from older versions without needing to modify the Attach Transform position.

See Also

attachTransform

The attachment point Unity uses on this Interactable (will use this object's position if none set).

Declaration
public Transform attachTransform { get; set; }
Property Value
Type Description
Transform

forceGravityOnDetach

Forces this object to have gravity when released (will still use pre-grab value if this is false).

Declaration
public bool forceGravityOnDetach { get; set; }
Property Value
Type Description
Boolean

gravityOnDetach

(Deprecated) Forces this object to have gravity when released (will still use pre-grab value if this is false).

Declaration
[Obsolete("gravityOnDetach has been deprecated. Use forceGravityOnDetach instead. (UnityUpgradable) -> forceGravityOnDetach")]
public bool gravityOnDetach { get; set; }
Property Value
Type Description
Boolean
Remarks

gravityOnDetach has been deprecated. Use forceGravityOnDetach instead.

matchAttachPosition

Match the position of the Interactor's attachment point when initializing the grab. This will override the position of attachTransform.

Declaration
public bool matchAttachPosition { get; set; }
Property Value
Type Description
Boolean
Remarks

This will initialize the dynamic attachment point of this object using the position of the Interactor's attachment point. This value can be overridden for a specific interactor by overriding ShouldMatchAttachPosition(IXRSelectInteractor).

See Also

matchAttachRotation

Match the rotation of the Interactor's attachment point when initializing the grab. This will override the rotation of attachTransform.

Declaration
public bool matchAttachRotation { get; set; }
Property Value
Type Description
Boolean
Remarks

This will initialize the dynamic attachment point of this object using the rotation of the Interactor's attachment point. This value can be overridden for a specific interactor by overriding ShouldMatchAttachRotation(IXRSelectInteractor).

See Also

movementType

Specifies how this object moves when selected, either through setting the velocity of the Rigidbody, moving the kinematic Rigidbody during Fixed Update, or by directly updating the Transform each frame.

Declaration
public XRBaseInteractable.MovementType movementType { get; set; }
Property Value
Type Description
XRBaseInteractable.MovementType
See Also

multipleGrabTransformersCount

The number of multiple grab transformers. These are the grab transformers used when there are multiple interactors selecting this object.

Declaration
public int multipleGrabTransformersCount { get; }
Property Value
Type Description
Int32
See Also

retainTransformParent

Whether Unity sets the parent of this object back to its original parent this object was a child of after this object is dropped.

Declaration
public bool retainTransformParent { get; set; }
Property Value
Type Description
Boolean

singleGrabTransformersCount

The number of single grab transformers. These are the grab transformers used when there is a single interactor selecting this object.

Declaration
public int singleGrabTransformersCount { get; }
Property Value
Type Description
Int32
See Also

smoothPosition

Whether Unity applies smoothing while following the position of the Interactor when selected.

Declaration
public bool smoothPosition { get; set; }
Property Value
Type Description
Boolean
See Also

smoothPositionAmount

Scale factor for how much smoothing is applied while following the position of the Interactor when selected. The larger the value, the closer this object will remain to the position of the Interactor.

Declaration
public float smoothPositionAmount { get; set; }
Property Value
Type Description
Single
See Also

smoothRotation

Apply smoothing while following the rotation of the Interactor when selected.

Declaration
public bool smoothRotation { get; set; }
Property Value
Type Description
Boolean
See Also

smoothRotationAmount

Scale factor for how much smoothing is applied while following the rotation of the Interactor when selected. The larger the value, the closer this object will remain to the rotation of the Interactor.

Declaration
public float smoothRotationAmount { get; set; }
Property Value
Type Description
Single
See Also

snapToColliderVolume

Adjust the dynamic attachment point to keep it on or inside the Colliders that make up this object.

Declaration
public bool snapToColliderVolume { get; set; }
Property Value
Type Description
Boolean
See Also

startingMultipleGrabTransformers

The grab transformers that this Interactable automatically links at startup (optional, may be empty). These are used when there are multiple interactors selecting this object.

Declaration
public List<XRBaseGrabTransformer> startingMultipleGrabTransformers { get; set; }
Property Value
Type Description
List<XRBaseGrabTransformer>
Remarks

To modify the grab transformers used after startup, the AddMultipleGrabTransformer(IXRGrabTransformer) or RemoveMultipleGrabTransformer(IXRGrabTransformer) methods should be used instead.

See Also

startingSingleGrabTransformers

The grab transformers that this Interactable automatically links at startup (optional, may be empty). These are used when there is a single interactor selecting this object.

Declaration
public List<XRBaseGrabTransformer> startingSingleGrabTransformers { get; set; }
Property Value
Type Description
List<XRBaseGrabTransformer>
Remarks

To modify the grab transformers used after startup, the AddSingleGrabTransformer(IXRGrabTransformer) or RemoveSingleGrabTransformer(IXRGrabTransformer) methods should be used instead.

See Also

throwAngularVelocityScale

Scale factor Unity applies to this object's angular velocity inherited from the Interactor when released.

Declaration
public float throwAngularVelocityScale { get; set; }
Property Value
Type Description
Single
See Also

throwOnDetach

Whether this object inherits the velocity of the Interactor when released.

Declaration
public bool throwOnDetach { get; set; }
Property Value
Type Description
Boolean

throwSmoothingCurve

The curve to use to weight thrown velocity smoothing (most recent frames to the right).

Declaration
public AnimationCurve throwSmoothingCurve { get; set; }
Property Value
Type Description
AnimationCurve
See Also

throwSmoothingDuration

Time period to average thrown velocity over.

Declaration
public float throwSmoothingDuration { get; set; }
Property Value
Type Description
Single
See Also

throwVelocityScale

Scale factor Unity applies to this object's velocity inherited from the Interactor when released.

Declaration
public float throwVelocityScale { get; set; }
Property Value
Type Description
Single
See Also

tightenPosition

Reduces the maximum follow position difference when using smoothing.

Declaration
public float tightenPosition { get; set; }
Property Value
Type Description
Single
Remarks

Fractional amount of how close the smoothed position should remain to the position of the Interactor when using smoothing. The value ranges from 0 meaning no bias in the smoothed follow distance, to 1 meaning effectively no smoothing at all.

See Also

tightenRotation

Reduces the maximum follow rotation difference when using smoothing.

Declaration
public float tightenRotation { get; set; }
Property Value
Type Description
Single
Remarks

Fractional amount of how close the smoothed rotation should remain to the rotation of the Interactor when using smoothing. The value ranges from 0 meaning no bias in the smoothed follow rotation, to 1 meaning effectively no smoothing at all.

See Also

trackPosition

Whether this object should follow the position of the Interactor when selected.

Declaration
public bool trackPosition { get; set; }
Property Value
Type Description
Boolean
See Also

trackRotation

Whether this object should follow the rotation of the Interactor when selected.

Declaration
public bool trackRotation { get; set; }
Property Value
Type Description
Boolean
See Also

useDynamicAttach

The grab pose will be based on the pose of the Interactor when the selection is made. Unity will create a dynamic attachment point for each Interactor that selects this component.

Declaration
public bool useDynamicAttach { get; set; }
Property Value
Type Description
Boolean
Remarks

A child GameObject will be created for each Interactor that selects this component to serve as the attachment point. These are cached and part of a shared pool used by all instances of XRGrabInteractable. Therefore, while a reference can be obtained by calling GetAttachTransform(IXRInteractor) while selected, you should typically not add any components to that GameObject unless you remove them after being released since it won't always be used by the same Interactable.

See Also

velocityDamping

Scale factor of how much to dampen the existing velocity when tracking the position of the Interactor. The smaller the value, the longer it takes for the velocity to decay.

Declaration
public float velocityDamping { get; set; }
Property Value
Type Description
Single
Remarks

Only applies when in VelocityTracking mode.

See Also

velocityScale

Scale factor Unity applies to the tracked velocity while updating the Rigidbody when tracking the position of the Interactor.

Declaration
public float velocityScale { get; set; }
Property Value
Type Description
Single
Remarks

Only applies when in VelocityTracking mode.

See Also

Methods

AddDefaultMultipleGrabTransformer()

Adds the default grab transformer (if the Multiple Grab Transformers list is empty) to the list of transformers used when there are multiple interactors selecting this object.

Declaration
protected virtual void AddDefaultMultipleGrabTransformer()
See Also

AddDefaultSingleGrabTransformer()

Adds the default grab transformer (if the Single Grab Transformers list is empty) to the list of transformers used when there is a single interactor selecting this object.

Declaration
protected virtual void AddDefaultSingleGrabTransformer()
See Also

AddMultipleGrabTransformer(IXRGrabTransformer)

Adds the given grab transformer to the list of transformers used when there are multiple interactors selecting this object.

Declaration
public void AddMultipleGrabTransformer(IXRGrabTransformer transformer)
Parameters
Type Name Description
IXRGrabTransformer transformer

The grab transformer to add.
See Also

AddSingleGrabTransformer(IXRGrabTransformer)

Adds the given grab transformer to the list of transformers used when there is a single interactor selecting this object.

Declaration
public void AddSingleGrabTransformer(IXRGrabTransformer transformer)
Parameters
Type Name Description
IXRGrabTransformer transformer

The grab transformer to add.
See Also

Awake()

See MonoBehaviour.

Declaration
protected override void Awake()
Overrides

ClearMultipleGrabTransformers()

Removes all grab transformers from the list of transformers used when there is are multiple interactors selecting this object.

Declaration
public void ClearMultipleGrabTransformers()
See Also

ClearSingleGrabTransformers()

Removes all grab transformers from the list of transformers used when there is a single interactor selecting this object.

Declaration
public void ClearSingleGrabTransformers()
See Also

Detach()

Updates the state of the object to finish the detach after being dropped. Automatically called during the end of the frame after being dropped.

Declaration
protected virtual void Detach()
Remarks

This method updates the velocity of the Rigidbody if configured to do so.

See Also

Drop()

Updates the state of the object due to being dropped and schedule to finish the detach during the end of the frame. Automatically called when exiting the Select state.

Declaration
protected virtual void Drop()
See Also

GetAttachTransform(IXRInteractor)

Gets the Transform that serves as the attachment point for a given Interactor.

Declaration
public override Transform GetAttachTransform(IXRInteractor interactor)
Parameters
Type Name Description
IXRInteractor interactor

The specific Interactor as context to get the attachment point for.
Returns
Type Description
Transform

Returns the attachment point Transform.
Overrides
Remarks

This should typically return the Transform of a child GameObject or the transform itself.

See Also

GetMultipleGrabTransformerAt(Int32)

Returns the grab transformer at index in the list of transformers used when there are multiple interactors selecting this object.

Declaration
public IXRGrabTransformer GetMultipleGrabTransformerAt(int index)
Parameters
Type Name Description
Int32 index

Index of the grab transformer to return. Must be smaller than multipleGrabTransformersCount and not negative.
Returns
Type Description
IXRGrabTransformer

Returns the grab transformer at the given index.
See Also

GetMultipleGrabTransformers(List<IXRGrabTransformer>)

Returns all transformers used when there are multiple interactors selecting this object into List results.

Declaration
public void GetMultipleGrabTransformers(List<IXRGrabTransformer> results)
Parameters
Type Name Description
List<IXRGrabTransformer> results

List to receive grab transformers.
Remarks

This method populates the list with the grab transformers at the time the method is called. It is not a live view, meaning grab transformers added or removed afterward will not be reflected in the results of this method. Clears results before adding to it.

See Also

GetSingleGrabTransformerAt(Int32)

Returns the grab transformer at index in the list of transformers used when there is a single interactor selecting this object.

Declaration
public IXRGrabTransformer GetSingleGrabTransformerAt(int index)
Parameters
Type Name Description
Int32 index

Index of the grab transformer to return. Must be smaller than singleGrabTransformersCount and not negative.
Returns
Type Description
IXRGrabTransformer

Returns the grab transformer at the given index.
See Also

GetSingleGrabTransformers(List<IXRGrabTransformer>)

Returns all transformers used when there is a single interactor selecting this object into List results.

Declaration
public void GetSingleGrabTransformers(List<IXRGrabTransformer> results)
Parameters
Type Name Description
List<IXRGrabTransformer> results

List to receive grab transformers.
Remarks

This method populates the list with the grab transformers at the time the method is called. It is not a live view, meaning grab transformers added or removed afterward will not be reflected in the results of this method. Clears results before adding to it.

See Also

Grab()

Updates the state of the object due to being grabbed. Automatically called when entering the Select state.

Declaration
protected virtual void Grab()
See Also

InitializeDynamicAttachPose(IXRSelectInteractor, Transform)

Unity calls this method automatically when the interactor first initiates selection of this interactable. Override this method to set the pose of the dynamic attachment point. Before this method is called, the transform is already set as a child GameObject with inherited Transform values.

Declaration
protected virtual void InitializeDynamicAttachPose(IXRSelectInteractor interactor, Transform dynamicAttachTransform)
Parameters
Type Name Description
IXRSelectInteractor interactor

The interactor that is initiating the selection.
Transform dynamicAttachTransform

The dynamic attachment Transform that serves as the attachment point for the given interactor.
Remarks

This method is only called when useDynamicAttach is enabled.

See Also

MoveMultipleGrabTransformerTo(IXRGrabTransformer, Int32)

Moves the given grab transformer in the list of transformers used when there are multiple interactors selecting this object. If the grab transformer is not in the list, this can be used to insert the grab transformer at the specified index.

Declaration
public void MoveMultipleGrabTransformerTo(IXRGrabTransformer transformer, int newIndex)
Parameters
Type Name Description
IXRGrabTransformer transformer

The grab transformer to move or add.
Int32 newIndex

New index of the grab transformer.
See Also

MoveSingleGrabTransformerTo(IXRGrabTransformer, Int32)

Moves the given grab transformer in the list of transformers used when there is a single interactor selecting this object. If the grab transformer is not in the list, this can be used to insert the grab transformer at the specified index.

Declaration
public void MoveSingleGrabTransformerTo(IXRGrabTransformer transformer, int newIndex)
Parameters
Type Name Description
IXRGrabTransformer transformer

The grab transformer to move or add.
Int32 newIndex

New index of the grab transformer.
See Also

OnDestroy()

See MonoBehaviour.

Declaration
protected override void OnDestroy()
Overrides

OnSelectEntering(SelectEnterEventArgs)

The XRInteractionManager calls this method right before the Interactor first initiates selection of an Interactable in a first pass.

Declaration
protected override void OnSelectEntering(SelectEnterEventArgs args)
Parameters
Type Name Description
SelectEnterEventArgs args

Event data containing the Interactor that is initiating the selection.
Overrides
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

OnSelectExited(SelectExitEventArgs)

The XRInteractionManager calls this method when the Interactor ends selection of an Interactable in a second pass.

Declaration
protected override void OnSelectExited(SelectExitEventArgs args)
Parameters
Type Name Description
SelectExitEventArgs args

Event data containing the Interactor that is ending the selection.
Overrides
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

OnSelectExiting(SelectExitEventArgs)

The XRInteractionManager calls this method right before the Interactor ends selection of an Interactable in a first pass.

Declaration
protected override void OnSelectExiting(SelectExitEventArgs args)
Parameters
Type Name Description
SelectExitEventArgs args

Event data containing the Interactor that is ending the selection.
Overrides
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

ProcessInteractable(XRInteractionUpdateOrder.UpdatePhase)

The XRInteractionManager calls this method to update the Interactable.

Declaration
public override void ProcessInteractable(XRInteractionUpdateOrder.UpdatePhase updatePhase)
Parameters
Type Name Description
XRInteractionUpdateOrder.UpdatePhase updatePhase

The update phase this is called during.
Overrides
Remarks

Please see the XRInteractionManager and XRInteractionUpdateOrder.UpdatePhase documentation for more details on update order.

See Also

RemoveMultipleGrabTransformer(IXRGrabTransformer)

Removes the given grab transformer from the list of transformers used when there is are multiple interactors selecting this object.

Declaration
public bool RemoveMultipleGrabTransformer(IXRGrabTransformer transformer)
Parameters
Type Name Description
IXRGrabTransformer transformer

The grab transformer to remove.
Returns
Type Description
Boolean

Returns true if transformer was removed from the list. Otherwise, returns false if transformer was not found in the list.
See Also

RemoveSingleGrabTransformer(IXRGrabTransformer)

Removes the given grab transformer from the list of transformers used when there is a single interactor selecting this object.

Declaration
public bool RemoveSingleGrabTransformer(IXRGrabTransformer transformer)
Parameters
Type Name Description
IXRGrabTransformer transformer

The grab transformer to remove.
Returns
Type Description
Boolean

Returns true if transformer was removed from the list. Otherwise, returns false if transformer was not found in the list.
See Also

SetupRigidbodyDrop(Rigidbody)

Setup the Rigidbody on this object due to being dropped. Automatically called when exiting the Select state.

Declaration
protected virtual void SetupRigidbodyDrop(Rigidbody rigidbody)
Parameters
Type Name Description
Rigidbody rigidbody

The Rigidbody on this object.
See Also

SetupRigidbodyGrab(Rigidbody)

Setup the Rigidbody on this object due to being grabbed. Automatically called when entering the Select state.

Declaration
protected virtual void SetupRigidbodyGrab(Rigidbody rigidbody)
Parameters
Type Name Description
Rigidbody rigidbody

The Rigidbody on this object.
See Also

ShouldMatchAttachPosition(IXRSelectInteractor)

Unity calls this method automatically when initializing the dynamic attach pose. Used to override matchAttachPosition for a specific interactor.

Declaration
protected virtual bool ShouldMatchAttachPosition(IXRSelectInteractor interactor)
Parameters
Type Name Description
IXRSelectInteractor interactor

The interactor that is initiating the selection.
Returns
Type Description
Boolean

Returns whether to match the position of the interactor's attachment point when initializing the grab.
See Also

ShouldMatchAttachRotation(IXRSelectInteractor)

Unity calls this method automatically when initializing the dynamic attach pose. Used to override matchAttachRotation for a specific interactor.

Declaration
protected virtual bool ShouldMatchAttachRotation(IXRSelectInteractor interactor)
Parameters
Type Name Description
IXRSelectInteractor interactor

The interactor that is initiating the selection.
Returns
Type Description
Boolean

Returns whether to match the rotation of the interactor's attachment point when initializing the grab.
See Also

ShouldSnapToColliderVolume(IXRSelectInteractor)

Unity calls this method automatically when initializing the dynamic attach pose. Used to override snapToColliderVolume for a specific interactor.

Declaration
protected virtual bool ShouldSnapToColliderVolume(IXRSelectInteractor interactor)
Parameters
Type Name Description
IXRSelectInteractor interactor

The interactor that is initiating the selection.
Returns
Type Description
Boolean

Returns whether to adjust the dynamic attachment point to keep it on or inside the Colliders that make up this object.
See Also

Extension Methods

See Also