Class XRRayInteractor
Interactor used for interacting with interactables at a distance. This is handled via ray casts that update the current set of valid targets for this interactor.
Inheritance
Inherited Members
Namespace: UnityEngine.XR.Interaction.Toolkit
Syntax
[DisallowMultipleComponent]
[AddComponentMenu("XR/XR Ray Interactor", 11)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.3/api/UnityEngine.XR.Interaction.Toolkit.XRRayInteractor.html")]
public class XRRayInteractor : XRBaseControllerInteractor, IXRHoverInteractor, IXRSelectInteractor, IXRTargetPriorityInteractor, IXRGroupMember, IXRInteractionStrengthInteractor, IXRActivateInteractor, IXRInteractor, ILineRenderable, IUIInteractorProperties
acceleration
Gravity of the projectile in the reference frame.
Declaration
public float acceleration { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
additionalFlightTime
Additional flight time after the projectile lands at the adjusted ground level. Increasing this value will make the end point drop lower in height.
Declaration
public float additionalFlightTime { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
additionalGroundHeight
Additional height below ground level that the projectile will continue to. Increasing this value will make the end point drop lower in height.
Declaration
public float additionalGroundHeight { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
allowAnchorControl
Allows the user to move the attach anchor point using the joystick.
Declaration
public bool allowAnchorControl { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
See Also
anchorRotateReferenceFrame
The optional reference frame to define the up axis when rotating the attach anchor point. When not set, rotates about the local up axis of the attach transform.
Declaration
public Transform anchorRotateReferenceFrame { get; set; }Property Value
| Type | Description |
|---|---|
| Transform |
See Also
anchorRotationMode
Gets or sets how the anchor rotation is controlled.
Declaration
public XRRayInteractor.AnchorRotationMode anchorRotationMode { get; set; }Property Value
| Type | Description |
|---|---|
| XRRayInteractor.AnchorRotationMode |
See Also
angle
The launch angle of the Projectile Curve. More specifically, this is the signed angle in degrees between the original attach forward direction and the plane of the reference frame, with positive angles when pointing upward.
Declaration
public float angle { get; }Property Value
| Type | Description |
|---|---|
| Single |
autoDeselect
Whether this Interactor will automatically deselect an Interactable after selecting it via hover for a period of time.
Declaration
public bool autoDeselect { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
Remarks
This only applies when an interactable is selected due to hoverToSelect.
See Also
blendVisualLinePoints
Blend the line sample points Unity uses for ray casting with the current pose of the controller. Use this to make the line visual stay connected with the controller instead of lagging behind.
Declaration
public bool blendVisualLinePoints { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
Remarks
When the controller is configured to sample tracking input directly before rendering to reduce
input latency, the controller may be in a new position or rotation relative to the starting point
of the sample curve used for ray casting.
A value of false will make the line visual stay at a fixed reference frame rather than bending
or curving towards the end of the ray cast line.
controlPointDistance
Increase this value to make the peak of the curve further from the start point.
Declaration
public float controlPointDistance { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
controlPointHeight
Increase this value to make the peak of the curve higher relative to the start point.
Declaration
public float controlPointHeight { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
currentNearestValidTarget
The nearest IXRInteractable object hit by the ray that was inserted into the valid targets list when not selecting anything.
Declaration
protected IXRInteractable currentNearestValidTarget { get; }Property Value
| Type | Description |
|---|---|
| IXRInteractable |
Remarks
Updated during PreprocessInteractor(XRInteractionUpdateOrder.UpdatePhase).
enableUIInteraction
Gets or sets whether this Interactor is able to affect UI.
Declaration
public bool enableUIInteraction { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
endPointDistance
Increase this value distance to make the end of the curve further from the start point.
Declaration
public float endPointDistance { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
endPointHeight
Decrease this value to make the end of the curve drop lower relative to the start point.
Declaration
public float endPointHeight { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
hitClosestOnly
Whether Unity considers only the closest Interactable as a valid target for interaction.
Declaration
public bool hitClosestOnly { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
Remarks
Enable this to make only the closest Interactable receive hover events. Otherwise, all hit Interactables will be considered valid and this Interactor will multi-hover.
See Also
hitDetectionType
Gets or sets which type of hit detection to use for the ray cast.
Declaration
public XRRayInteractor.HitDetectionType hitDetectionType { get; set; }Property Value
| Type | Description |
|---|---|
| XRRayInteractor.HitDetectionType |
hoverTimeToSelect
Number of seconds for which this Interactor must hover over an Interactable to select it if Hover To Select is enabled.
Declaration
public float hoverTimeToSelect { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
hoverToSelect
Whether this Interactor will automatically select an Interactable after hovering over it for a period of time.
Declaration
public bool hoverToSelect { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
See Also
isSelectActive
(Read Only) Indicates whether this Interactor is in a state where it could select.
Declaration
public override bool isSelectActive { get; }Property Value
| Type | Description |
|---|---|
| Boolean |
Overrides
lineType
Gets or sets the type of ray cast.
Declaration
public XRRayInteractor.LineType lineType { get; set; }Property Value
| Type | Description |
|---|---|
| XRRayInteractor.LineType |
maxRaycastDistance
Gets or sets the max distance of ray cast when the line type is a straight line. Increasing this value will make the line reach further.
Declaration
public float maxRaycastDistance { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
raycastMask
Gets or sets layer mask used for limiting ray cast targets.
Declaration
public LayerMask raycastMask { get; set; }Property Value
| Type | Description |
|---|---|
| LayerMask |
raycastSnapVolumeInteraction
Whether ray cast should include or ignore hits on trigger colliders that are snap volume colliders, even if the ray cast is set to ignore triggers. If you are not using gaze assistance or XR Interactable Snap Volume components, you should set this property to Ignore to avoid the performance cost.
Declaration
public XRRayInteractor.QuerySnapVolumeInteraction raycastSnapVolumeInteraction { get; set; }Property Value
| Type | Description |
|---|---|
| XRRayInteractor.QuerySnapVolumeInteraction |
Remarks
When set to Collide when raycastTriggerInteraction is set to ignore trigger colliders
(when set to Ignore or when set to UseGlobal
while queriesHitTriggers is false),
the ray cast query will be modified to include trigger colliders, but then this behavior will ignore any trigger collider
hits that are not snap volumes.
When set to Ignore when raycastTriggerInteraction is set to hit trigger colliders
(when set to Collide or when set to UseGlobal
while queriesHitTriggers is true),
this behavior will ignore any trigger collider hits that are snap volumes.
See Also
raycastTriggerInteraction
Gets or sets type of interaction with trigger colliders via ray cast.
Declaration
public QueryTriggerInteraction raycastTriggerInteraction { get; set; }Property Value
| Type | Description |
|---|---|
| QueryTriggerInteraction |
rayOriginTransform
The starting position and direction of any ray casts.
Declaration
public Transform rayOriginTransform { get; set; }Property Value
| Type | Description |
|---|---|
| Transform |
Remarks
Automatically instantiated and set in Awake() if null and initialized with the pose of the attachTransform. Setting this will not automatically destroy the previous object.
referenceFrame
The reference frame of the curve to define the ground plane and up. If not set at startup it will try to find the Origin GameObject, and if that does not exist it will use global up and origin by default.
Declaration
public Transform referenceFrame { get; set; }Property Value
| Type | Description |
|---|---|
| Transform |
See Also
rotateSpeed
Speed that the anchor is rotated when anchorRotationMode is set to RotateOverTime.
Declaration
public float rotateSpeed { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
sampleFrequency
The number of sample points Unity uses to approximate curved paths. Larger values produce a better quality approximate at the cost of reduced performance due to the number of ray casts.
Declaration
public int sampleFrequency { get; set; }Property Value
| Type | Description |
|---|---|
| Int32 |
Remarks
A value of n will result in n - 1 line segments for ray cast. This property is not used when using StraightLine since the value would always be 2.
See Also
sphereCastRadius
Gets or sets radius used for sphere casting. Will use regular ray casting if set to 0 or less.
Declaration
public float sphereCastRadius { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
timeToAutoDeselect
Number of seconds for which this Interactor will keep an Interactable selected before automatically deselecting it.
Declaration
public float timeToAutoDeselect { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
Remarks
This only applies when an interactable is selected due to hoverToSelect.
See Also
translateSpeed
Speed that the anchor is translated.
Declaration
public float translateSpeed { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
useForceGrab
Force grab moves the object to your hand rather than interacting with it at a distance.
Declaration
public bool useForceGrab { get; set; }Property Value
| Type | Description |
|---|---|
| Boolean |
velocity
Initial velocity of the projectile. Increasing this value will make the curve reach further.
Declaration
public float velocity { get; set; }Property Value
| Type | Description |
|---|---|
| Single |
See Also
Methods
Awake()
See MonoBehaviour.
Declaration
protected override void Awake()Overrides
CanHover(IXRHoverInteractable)
Determines if the Interactable is valid for hover this frame.
Declaration
public override bool CanHover(IXRHoverInteractable interactable)Parameters
| Type | Name | Description |
|---|---|---|
| IXRHoverInteractable | interactable | Interactable to check. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if the Interactable can be hovered over this frame. |
Overrides
See Also
CanSelect(IXRSelectInteractable)
Determines if the Interactable is valid for selection this frame.
Declaration
public override bool CanSelect(IXRSelectInteractable interactable)Parameters
| Type | Name | Description |
|---|---|---|
| IXRSelectInteractable | interactable | Interactable to check. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if the Interactable can be selected this frame. |
Overrides
See Also
GetHoverTimeToSelect(IXRInteractable)
Gets the number of seconds for which this interactor must hover over the interactable to select it if hoverToSelect is enabled.
Declaration
protected virtual float GetHoverTimeToSelect(IXRInteractable interactable)Parameters
| Type | Name | Description |
|---|---|---|
| IXRInteractable | interactable | The interactable to get the duration for. |
Returns
| Type | Description |
|---|---|
| Single | Returns the number of seconds for which this Interactor must hover over an Interactable to select it. |
See Also
GetLinePoints(ref Vector3[], out Int32)
Gets the polygonal chain represented by a list of endpoints which form line segments to approximate the curve. Positions are in world space coordinates.
Declaration
public bool GetLinePoints(ref Vector3[] linePoints, out int numPoints)Parameters
| Type | Name | Description |
|---|---|---|
| Vector3[] | linePoints | When this method returns, contains the sample points if successful. |
| Int32 | numPoints | When this method returns, contains the number of sample points if successful. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if the sample points form a valid line, such as by having at least two points. Otherwise, returns false. |
Implements
GetTimeToAutoDeselect(IXRInteractable)
Gets the number of seconds for which this interactor will keep the interactable selected before automatically deselecting it.
Declaration
protected virtual float GetTimeToAutoDeselect(IXRInteractable interactable)Parameters
| Type | Name | Description |
|---|---|---|
| IXRInteractable | interactable | The interactable to get the duration for. |
Returns
| Type | Description |
|---|---|
| Single | Returns the number of seconds for which this Interactor will keep an Interactable selected before automatically deselecting it. |
See Also
GetValidTargets(List<IXRInteractable>)
Retrieve the list of Interactables that this Interactor could possibly interact with this frame. This list is sorted by priority (with highest priority first).
Declaration
public override void GetValidTargets(List<IXRInteractable> targets)Parameters
| Type | Name | Description |
|---|---|---|
| List<IXRInteractable> | targets | The results list to populate with Interactables that are valid for selection or hover. |
Overrides
Remarks
When implementing this method, Unity expects you to clear targets before adding to it.
IsOverUIGameObject()
Use this to determine if the ray is currently hovering over a UI GameObject.
Declaration
public bool IsOverUIGameObject()Returns
| Type | Description |
|---|---|
| Boolean | Returns true if hovering over a UI element. Otherwise, returns false. |
Remarks
enableUIInteraction must be enabled, otherwise the function will always return false.
See Also
OnDisable()
See MonoBehaviour.
Declaration
protected override void OnDisable()Overrides
OnDrawGizmosSelected()
See MonoBehaviour.
Declaration
protected virtual void OnDrawGizmosSelected()OnEnable()
See MonoBehaviour.
Declaration
protected override void OnEnable()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 Interactable that is being selected. |
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 Interactable that is no longer selected. |
Overrides
Remarks
args is only valid during this method call, do not hold a reference to it.
See Also
OnValidate()
See MonoBehaviour.
Declaration
protected void OnValidate()PreprocessInteractor(XRInteractionUpdateOrder.UpdatePhase)
The XRInteractionManager or containing IXRInteractionGroup calls this method to update the Interactor before interaction events occur. Interactors should use this method to do tasks like determine their valid targets.
Declaration
public override void PreprocessInteractor(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
ProcessInteractor(XRInteractionUpdateOrder.UpdatePhase)
The XRInteractionManager or containing IXRInteractionGroup calls this method to update the Interactor after interaction events occur.
Declaration
public override void ProcessInteractor(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
RotateAnchor(Transform, Single)
Rotates the attach anchor for this interactor. This can be useful to rotate a held object.
Declaration
protected virtual void RotateAnchor(Transform anchor, float directionAmount)Parameters
| Type | Name | Description |
|---|---|---|
| Transform | anchor | The attach transform of the interactor. |
| Single | directionAmount | The rotation amount. |
RotateAnchor(Transform, Vector2, Quaternion)
Rotates the attach anchor for this interactor to match a given direction. This can be useful to compute a direction angle for teleportation.
Declaration
protected virtual void RotateAnchor(Transform anchor, Vector2 direction, Quaternion referenceRotation)Parameters
| Type | Name | Description |
|---|---|---|
| Transform | anchor | The attach transform of the interactor. |
| Vector2 | direction | The directional input. |
| Quaternion | referenceRotation | The reference rotation to define the up axis for rotation. |
TranslateAnchor(Transform, Transform, Single)
Translates the attach anchor for this interactor. This can be useful to move a held object closer or further away from the interactor.
Declaration
protected virtual void TranslateAnchor(Transform rayOrigin, Transform anchor, float directionAmount)Parameters
| Type | Name | Description |
|---|---|---|
| Transform | rayOrigin | The starting position and direction of any ray casts. |
| Transform | anchor | The attach transform of the interactor. |
| Single | directionAmount | The translation amount. |
TryGetCurrent3DRaycastHit(out RaycastHit)
Gets the first 3D ray cast hit, if any ray cast hits are available.
Declaration
public bool TryGetCurrent3DRaycastHit(out RaycastHit raycastHit)Parameters
| Type | Name | Description |
|---|---|---|
| RaycastHit | raycastHit |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if a hit occurred, implying the ray cast hit information is valid. Otherwise, returns false. |
TryGetCurrent3DRaycastHit(out RaycastHit, out Int32)
Gets the first 3D ray cast hit, if any ray cast hits are available.
Declaration
public bool TryGetCurrent3DRaycastHit(out RaycastHit raycastHit, out int raycastEndpointIndex)Parameters
| Type | Name | Description |
|---|---|---|
| RaycastHit | raycastHit | When this method returns, contains the ray cast hit if available; otherwise, the default value. |
| Int32 | raycastEndpointIndex | When this method returns, contains the index of the sample endpoint if a hit occurred.
Otherwise, a value of |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if a hit occurred, implying the ray cast hit information is valid. Otherwise, returns false. |
TryGetCurrentRaycast(out Nullable<RaycastHit>, out Int32, out Nullable<RaycastResult>, out Int32, out Boolean)
Gets the first 3D and UI ray cast hits, if any ray cast hits are available.
Declaration
public bool TryGetCurrentRaycast(out RaycastHit? raycastHit, out int raycastHitIndex, out RaycastResult? uiRaycastHit, out int uiRaycastHitIndex, out bool isUIHitClosest)Parameters
| Type | Name | Description |
|---|---|---|
| Nullable<RaycastHit> | raycastHit | When this method returns, contains the ray cast hit if available; otherwise, the default value. |
| Int32 | raycastHitIndex | When this method returns, contains the index of the sample endpoint if a hit occurred.
Otherwise, a value of |
| Nullable<RaycastResult> | uiRaycastHit | When this method returns, contains the UI ray cast result if available; otherwise, the default value. |
| Int32 | uiRaycastHitIndex | When this method returns, contains the index of the sample endpoint if a hit occurred.
Otherwise, a value of |
| Boolean | isUIHitClosest | When this method returns, contains whether the UI ray cast result was the closest hit. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if either hit occurred, implying the ray cast hit information is valid. Otherwise, returns false. |
TryGetCurrentUIRaycastResult(out RaycastResult)
Gets the first UI ray cast result, if any ray cast results are available.
Declaration
public bool TryGetCurrentUIRaycastResult(out RaycastResult raycastResult)Parameters
| Type | Name | Description |
|---|---|---|
| RaycastResult | raycastResult |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if a hit occurred, implying the ray cast hit information is valid. Otherwise, returns false. |
TryGetCurrentUIRaycastResult(out RaycastResult, out Int32)
Gets the first UI ray cast result, if any ray cast results are available.
Declaration
public bool TryGetCurrentUIRaycastResult(out RaycastResult raycastResult, out int raycastEndpointIndex)Parameters
| Type | Name | Description |
|---|---|---|
| RaycastResult | raycastResult | When this method returns, contains the UI ray cast result if available; otherwise, the default value. |
| Int32 | raycastEndpointIndex | When this method returns, contains the index of the sample endpoint if a hit occurred.
Otherwise, a value of |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if a hit occurred, implying the ray cast hit information is valid. Otherwise, returns false. |
TryGetHitInfo(out Vector3, out Vector3, out Int32, out Boolean)
Gets the current ray cast hit information, if a hit occurs. It returns the world position and the normal vector of the hit point, and its position in linePoints.
Declaration
public bool TryGetHitInfo(out Vector3 position, out Vector3 normal, out int positionInLine, out bool isValidTarget)Parameters
| Type | Name | Description |
|---|---|---|
| Vector3 | position | When this method returns, contains the world position of the ray impact point if a hit occurred. |
| Vector3 | normal | When this method returns, contains the world normal of the surface the ray hit if a hit occurred. |
| Int32 | positionInLine | When this method returns, contains the index of the sample endpoint within the list of points returned by GetLinePoints(ref Vector3[], out Int32)
where a hit occurred. Otherwise, a value of |
| Boolean | isValidTarget | When this method returns, contains whether both a hit occurred and it is a valid target for interaction. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if a hit occurs, implying the ray cast hit information is valid. Otherwise, returns false. |
Implements
TryGetUIModel(out TrackedDeviceModel)
Attempts to retrieve the current UI Model.
Declaration
public bool TryGetUIModel(out TrackedDeviceModel model)Parameters
| Type | Name | Description |
|---|---|---|
| TrackedDeviceModel | model | The returned model that reflects the UI state of this Interactor. |
Returns
| Type | Description |
|---|---|
| Boolean | Returns true if the model was able to retrieved. Otherwise, returns false. |
Implements
UpdateUIModel(ref TrackedDeviceModel)
Updates the current UI Model to match the state of the Interactor.
Declaration
public virtual void UpdateUIModel(ref TrackedDeviceModel model)Parameters
| Type | Name | Description |
|---|---|---|
| TrackedDeviceModel | model | The returned model that will match this Interactor. |