Class XRGrabInteractable
Interactable component that allows basic "grab" functionality. Can attach to an Interactor that selects this Interactable component and follow it around while obeying physics (and inherit velocity when released).
Inherited Members
Namespace: UnityEngine.XR.Interaction.Toolkit
Syntax
[SelectionBase]
[DisallowMultipleComponent]
[CanSelectMultiple(false)]
[RequireComponent(typeof(Rigidbody))]
[AddComponentMenu("XR/XR Grab Interactable", 11)]
[HelpURL("https://docs.unity.cn/Packages/com.unity.xr.interaction.toolkit@2.1/api/UnityEngine.XR.Interaction.Toolkit.XRGrabInteractable.html")]
public class XRGrabInteractable : XRBaseInteractable, IXRActivateInteractable, IXRHoverInteractable, IXRSelectInteractable, IXRInteractableProperties
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
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 |
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
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
Awake()
See MonoBehaviour.
Declaration
protected override void Awake()Overrides
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
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
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
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. |