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.
Inherited Members
Namespace: UnityEngine.XR.Interaction.Toolkit
Syntax
[SelectionBase]
[DisallowMultipleComponent]
[RequireComponent(typeof(Rigidbody))]
[AddComponentMenu("XR/XR Grab Interactable", 11)]
[HelpURL("https://docs.unity.cn/Packages/com.unity.xr.interaction.toolkit@2.4/api/UnityEngine.XR.Interaction.Toolkit.XRGrabInteractable.html")]
public class XRGrabInteractable : XRBaseInteractable, IXRActivateInteractable, IXRHoverInteractable, IXRSelectInteractable, IXRFocusInteractable, IXRInteractionStrengthInteractable, IXRInteractable, IXROverridesGazeAutoSelect
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 |
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
reinitializeDynamicAttachEverySingleGrab
Re-initialize the dynamic attachment pose when changing from multiple grabs back to a single grab. Use this if you want to keep the current pose of the object after releasing a second hand rather than reverting back to the attach pose from the original grab.
Declaration
public bool reinitializeDynamicAttachEverySingleGrab { get; set; }
Property Value
Type | Description |
---|---|
Boolean |
Remarks
selectMode must be set to Multiple for this setting to take effect.
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 |
secondaryAttachTransform
The secondary attachment point to use on this Interactable for multi-hand interaction (will use the second interactor's attach transform if none set). Used for multi-grab interactions.
Declaration
public Transform secondaryAttachTransform { get; set; }
Property Value
Type | Description |
---|---|
Transform |
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 used to weight velocity smoothing upon throwing (most recent frames to the right).
Declaration
public AnimationCurve throwSmoothingCurve { get; set; }
Property Value
Type | Description |
---|---|
AnimationCurve |
Remarks
By default this curve is flat with a 1.0 value so all smoothing values are treated equally across the smoothing duration.
See Also
throwSmoothingDuration
This value represents the time over which collected samples are used for velocity calculation (up to a max of 20 previous frames, which is dependent on both Smoothing Duration and framerate).
Declaration
public float throwSmoothingDuration { get; set; }
Property Value
Type | Description |
---|---|
Single |
Remarks
As an example, if this value is set to 0.25, position and velocity values will be averaged over the past 0.25 seconds. Each of those values is weighted (multiplied) by the throwSmoothingCurve as well.
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 XRGeneralGrabTransformer (if the Single or Multiple Grab Transformers lists are 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 |
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 |
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. |