Class NearFarInteractor
Interactor that uses two IInteractionCaster references to find valid targets. The near caster is simpler and not assumed to have any line based casting, while the far caster implements ICurveInteractionCaster to find valid targets, and optionally IUIModelUpdater which is used to support UI interaction and sort interaction points.
Inheritance
Implements
Inherited Members
Namespace: UnityEngine.XR.Interaction.Toolkit.Interactors
Assembly: Unity.XR.Interaction.Toolkit.dll
Syntax
[DisallowMultipleComponent]
[AddComponentMenu("XR/Interactors/Near-Far Interactor", 11)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@3.2/api/UnityEngine.XR.Interaction.Toolkit.Interactors.NearFarInteractor.html")]
public class NearFarInteractor : XRBaseInputInteractor, IXRHoverInteractor, IXRSelectInteractor, IXRTargetPriorityInteractor, IXRGroupMember, IXRInteractionStrengthInteractor, IXRActivateInteractor, IXRInteractor, IXRRayProvider, IUIHoverInteractor, IUIInteractor, ICurveInteractionDataProviderProperties
blockUIOnInteractableSelection
Enabling this option will block UI interaction when selecting interactables.
Declaration
public bool blockUIOnInteractableSelection { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
curveOrigin
The transform used to determine the origin of the curve.
Declaration
public Transform curveOrigin { get; }Property Value
| Type | Description |
|---|---|
| Transform |
enableFarCasting
Determines if the far caster will be used to find valid targets for this interactor.
Declaration
public bool enableFarCasting { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
enableNearCasting
Determines if the near caster will be used to find valid targets for this interactor.
Declaration
public bool enableNearCasting { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
enableUIInteraction
Enable to affect Unity UI GameObjects in a way that is similar to a mouse pointer. Requires the XR UI Input Module on the Event System.
Declaration
public bool enableUIInteraction { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
farAttachMode
Determines how the attach transform is adjusted on far select. This typically results in whether the interactable stays distant at the far hit point or moves to the near hand.
Declaration
public InteractorFarAttachMode farAttachMode { get; set; }Property Value
| Type | Description |
|---|---|
| InteractorFarAttachMode |
farInteractionCaster
Reference to the far interaction caster used to find valid targets for this interactor.
Declaration
public ICurveInteractionCaster farInteractionCaster { get; set; }Property Value
| Type | Description |
|---|---|
| ICurveInteractionCaster |
interactionAttachController
Reference to the attach controller used to control the attach transform.
Declaration
public IInteractionAttachController interactionAttachController { get; set; }Property Value
| Type | Description |
|---|---|
| IInteractionAttachController |
nearCasterSortingStrategy
Strategy used to compute the the distance used to sort valid targets discovered by the near interaction caster.
Declaration
public NearFarInteractor.NearCasterSortingStrategy nearCasterSortingStrategy { get; set; }Property Value
| Type | Description |
|---|---|
| NearFarInteractor.NearCasterSortingStrategy |
nearInteractionCaster
Reference to the near interaction caster used to find valid targets for this interactor.
Declaration
public IInteractionCaster nearInteractionCaster { get; set; }Property Value
| Type | Description |
|---|---|
| IInteractionCaster |
selectionRegion
The current region, Near or Far, of the interactable when this interactor has a selection. When not selecting, the value is None. Exposed as a bindable variable to allow users to subscribe to changes.
Declaration
public IReadOnlyBindableVariable<NearFarInteractor.Region> selectionRegion { get; }Property Value
| Type | Description |
|---|---|
| IReadOnlyBindableVariable<NearFarInteractor.Region> |
Remarks
More technically, this is based on whether the attach transform has an offset or not. This value can start at Far when an interactable hit by the far interaction caster is selected but change to Near as the object is pulled all the way closer.
See Also
sortNearTargetsAfterTargetFilter
If true, the interactor will sort the near caster's valid targets after the targetFilter has been applied. Generally, the target filter also takes care of sorting, so this option should only be used if the target filter does not sort. Not used if no target filter is present.
Declaration
public bool sortNearTargetsAfterTargetFilter { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
uiHoverEntered
The event that is called when the Interactor begins hovering over a UI element.
Declaration
public UIHoverEnterEvent uiHoverEntered { get; set; }Property Value
| Type | Description |
|---|---|
| UIHoverEnterEvent |
Remarks
The UIHoverEventArgs passed to each listener is only valid while the event is invoked, do not hold a reference to it.
uiHoverExited
The event that is called when this Interactor ends hovering over a UI element.
Declaration
public UIHoverExitEvent uiHoverExited { get; set; }Property Value
| Type | Description |
|---|---|
| UIHoverExitEvent |
Remarks
The UIHoverEventArgs passed to each listener is only valid while the event is invoked, do not hold a reference to it.
uiPressInput
Input to use for pressing UI elements. Functions like a mouse button when pointing over UI.
Declaration
public XRInputButtonReader uiPressInput { get; set; }Property Value
| Type | Description |
|---|---|
| XRInputButtonReader |
uiScrollInput
Input to use for scrolling UI elements. Functions like a mouse scroll wheel when pointing over UI.
Declaration
public XRInputValueReader<Vector2> uiScrollInput { get; set; }Property Value
| Type | Description |
|---|---|
| XRInputValueReader<Vector2> |
Methods
Awake()
See MonoBehaviour.
Declaration
protected override void Awake()Overrides
GetEvaluatorForSortingStrategy(NearCasterSortingStrategy)
Gets the selected interactor distance evaluator strategy used to sort valid interactable targets discovered by the near interaction caster. The selected sorting strategy can have non-trivial performance implications as the computation will scale according to the quantity of valid targets and the strategy used.
Declaration
protected virtual IInteractorDistanceEvaluator GetEvaluatorForSortingStrategy(NearFarInteractor.NearCasterSortingStrategy strategy)Parameters
| Type | Name | Description |
|---|---|---|
| NearFarInteractor.NearCasterSortingStrategy | strategy | Strategy to apply. |
Returns
| Type | Description |
|---|---|
| IInteractorDistanceEvaluator | IInteractorDistanceEvaluator instance associated with NearFarInteractor.NearCasterSortingStrategy parameter. |
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.
InitializeReferences()
Initializes all required references for this interactor to work. If components are missing, we try to find local components first, but if none are found, default implementations are added.
Declaration
protected virtual void InitializeReferences()OnDisable()
See MonoBehaviour.
Declaration
protected override void OnDisable()Overrides
OnEnable()
See MonoBehaviour.
Declaration
protected override void OnEnable()Overrides
OnSelectEntered(SelectEnterEventArgs)
The XRInteractionManager calls this method when the Interactor first initiates selection of an Interactable in a second pass.
Declaration
protected override void OnSelectEntered(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
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
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 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
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
OnUIHoverEntered(UIHoverEventArgs)
The XRUIInputModule calls this method when the Interactor begins hovering over a UI element.
Declaration
protected virtual void OnUIHoverEntered(UIHoverEventArgs args)Parameters
| Type | Name | Description |
|---|---|---|
| UIHoverEventArgs | args | Event data containing the UI element that is being hovered over. |
Remarks
args is only valid during this method call, do not hold a reference to it.
See Also
OnUIHoverExited(UIHoverEventArgs)
The XRUIInputModule calls this method when the Interactor ends hovering over a UI element.
Declaration
protected virtual void OnUIHoverExited(UIHoverEventArgs args)Parameters
| Type | Name | Description |
|---|---|---|
| UIHoverEventArgs | args | Event data containing the UI element that is no longer hovered over. |
Remarks
args is only valid during this method call, do not hold a reference to it.
See Also
PreprocessInteractor(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
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 | When this method returns, contains the UI ray cast result if available; otherwise, the default value.
Otherwise, a value of |
Returns
| Type | Description |
|---|---|
| bool | Returns true if a hit occurred, implying the ray cast hit information is valid. Otherwise, returns false. |
TryGetCurveEndNormal(out Vector3, bool)
Attempts to determine the normal at the endpoint of the curve. This method will transform the captured local direction of the normal on select if tracking a snapped attach point.
Declaration
public EndPointType TryGetCurveEndNormal(out Vector3 endNormal, bool snapToSelectedAttachIfAvailable = false)Parameters
| Type | Name | Description |
|---|---|---|
| Vector3 | endNormal | Output parameter that will hold the normal vector at the curve's endpoint. |
| bool | snapToSelectedAttachIfAvailable | If true, the method will attempt to snap to the selected attach point, if it's available. |
Returns
| Type | Description |
|---|---|
| EndPointType | Returns an EndPointType indicating the type of the endpoint where the normal was determined. |
TryGetCurveEndPoint(out Vector3, bool, bool)
Attempts to determine the end point of the curve. The end point can be set to either an attach point or the end of a raycast hit.
Declaration
public EndPointType TryGetCurveEndPoint(out Vector3 endPoint, bool snapToSelectedAttachIfAvailable = false, bool snapToSnapVolumeIfAvailable = false)Parameters
| Type | Name | Description |
|---|---|---|
| Vector3 | endPoint | Output parameter that will hold the end point vector. |
| bool | snapToSelectedAttachIfAvailable | If set to true, the method will try to snap to the selected attach point, if available. |
| bool | snapToSnapVolumeIfAvailable | If set to true, the method will try to snap to the nearest snap volume, if available. |
Returns
| Type | Description |
|---|---|
| EndPointType | Returns an EndPointType indicating the type of the end point determined. |
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 |
|---|---|
| bool | Returns true if the model was retrieved. Otherwise, returns false. |
UpdateUIModel(ref TrackedDeviceModel)
Updates the current UI Model to match the state of the Interactor.
Declaration
public void UpdateUIModel(ref TrackedDeviceModel model)Parameters
| Type | Name | Description |
|---|---|---|
| TrackedDeviceModel | model | The returned model that will match this Interactor. |