Near-Far Interactor
Interactor used for interacting with interactables both within arms reach and at a distance. The near-far interactor allows the seamless transition from far to near interaction.
This interactor uses sphere casts to detect eligible nearby interactable targets and a configurable ray caster to detect eligible interactable targets at a distance. In the starter assets and demo scene, a Near-Far Interactor component is used as the primary interactor for grabbing and manipulating interactable objects as part of the Left and Right Interactor Prefabs.
You can configure the far casting options to support interaction with UI elements. (Use a separate Poke Interactor for direct interaction.)
Note
The near-far interactor is designed to integrate the functionality of both XR Direct Interactor and XR Ray Interactor, though there are two notable gaps to keep in mind.
- For mobile AR devices, the ray interactor is still required for raycasting AR data, as this Near-Far Interactor does not support this use case.
- The Near-Far Interactor does not support using the joystick to control the attach transform for scaling, as the XR Ray Interactor does.
Supporting components
You can use the following additional components with a near-far interactor:
- Interaction Attach Controller: Provides options for how the user can manipulate an object "grabbed" by the far-casting aspect of the interactor.
- Curve Visual Controller, Line Renderer, and Sorting Group: draw a visual line along the casting path.
- Curve Interaction Caster: Provides options for specifying the far-casting behavior.
- Sphere Interaction Caster: Provides options for specifying the near-casting behavior.
- Simple Audio Feedback: Play audio clips when interactor events happen. (Replaces the Audio Events properties of the interactor.)
- Simple Haptic Feedback: Play haptic impulses when interactor events happen. (Replaces the Haptic Events properties of the interactor.)
- XR Interaction Group: Define groups of interactors to mediate which has priority for an interaction.
Base properties
The near-far interactor has many properties that you can set to modify how the interactor behaves. Some of these properties are organized into sections and don't appear in the Inspector window until you enable another property or expand a section.
| Property | Description |
|---|---|
| Interaction Manager | The XRInteractionManager that this interactor will communicate with (will find one if None). |
| Interaction Layer Mask | Allows interaction with interactables whose Interaction Layer Mask contains any Layer in this Interaction Layer Mask. |
| Handedness | Represents which hand or controller the interactor is associated with. This information is used by the interaction system when querying whether the right or the left hand is selecting an interactable. |
| Interaction Attach Controller | Reference to the attach controller component used to control the attach transform. A component with default settings is added if you do not set this property value. |
| Near Casting configuration | Configure options for interacting with interactables that are close enough to touch. |
| Far Casting configuration | Configure options for interacting with interactables that are out of arm's reach. |
| Selection Configuration | Controls selection behavior. Click the triangle icon to expand the section. Note that you configure the input controls used for selection in the Input Configuration section. |
| Input Configuration | Specify input bindings for the select and activate actions. Click the triangle icon to expand the section. |
| Interactor Filters | Identifies any filters this interactor uses to winnow detected interactables. You can create filter classes to provide custom logic to limit which interactables an interactor can interact with. Filtering occurs after the interactor has performed a raycast to detect eligible interactables. |
| Interactor Events | The events dispatched by this interactor. You can add event handlers in other components in the scene or prefab and they are invoked when the event occurs. |
Near-casting configuration
Check the Enable Near Casting option to configure the interactor to interact with nearby objects.
Note
You can set the characteristics of the sphere cast used to detect eligible interactables for an interaction with a Sphere Interaction Caster component. You can also create a custom component that implements the IInteractionCaster interface.
| Property | Description |
|---|---|
| Enable Near Casting | Determines if the near interaction caster is activated to find valid nearby targets. Default is true. |
| Near Caster | Reference to the near interaction caster component used for near interactions. Must implement IInteractionCaster. A component with default settings is added at runtime when you do not set this property value. |
| Sorting Strategy | Strategy for sorting targets detected by the near interaction caster. Options are None, Square Distance, Interactable Based, and Closest Point On Collider. |
| Sort Near Targets After Target Filter | Enable to sort near targets after any interactor filters are applied. You should only enable this if the filters do not already sort targets. Ignored if no target filters are set. |
You can choose from the following strategies for sorting valid targets discovered by the near interaction caster.
- None: No sorting is performed.
- Square Distance: Sorting based on the square distance between the interactor and interactable attach transform world positions. Most efficient.
- Interactable Based: Sorting based on the interactable's defined sorting strategy, usually collider based.
- Closest Point On Collider: Sorting based on the square distance between the interactor's attach transform world position and the closest point on the interactable's collider. Used for high fidelity disambiguation.
Far-casting configuration
Check the Enable Far Casting option to configure the interactor to interact with far away objects.
Note
You can set the characteristics of the caster used to detect eligible interactables for an interaction with a Curve Interaction Caster component. You can also create a custom component that implements the ICurveInteractionCaster interface.
| Property | Description |
|---|---|
| Enable Far Casting | Determines if the far interaction caster is activated to find valid distant targets. Default is true. |
| Far Caster | Reference to the far interaction caster component used for far interactions. Must implement ICurveInteractionCaster. A component with default settings is added at runtime when you do not set this property value. |
| Far Attach Mode | Determines how the attachment point 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. |
| UI Interaction | Allows the interactor's far-casting behavior to interact with UI elements at a distance. Default is true. |
| Block UI On Interactable Selection | Blocks UI interaction when an interactable is selected. Default is true. |
| UI Press Input | Defines the input used for pressing UI elements, functioning like a mouse button when pointing over UI. Implemented as an XRInputButtonReader. |
| UI Scroll Input | Defines the input used for scrolling UI elements, functioning like a mouse scroll wheel when pointing over UI. Implemented as an XRInputValueReader<Vector2>. |
Selection Configuration
Use the options in the Selection Configuration section to configure selection-related behavior. For example, you can specify whether the user must hold a button continuously to maintain selection or just press a button to toggle selection on and off.
Note
Configure the input for selection with the Select Input property in the Input Configuration section of the Inspector.
| Property | Description |
|---|---|
| Select Action Trigger | Choose how the configured Select Input control triggers the selection of an interactable object. |
| Keep Selected Target Valid | Whether to keep selecting an interactable after initially selecting it even when it is no longer a valid target. Enable to make the XRInteractionManager retain the selection even if the interactable is not contained within the list of valid targets. Disable to make the Interaction Manager clear the selection if it isn't within the list of valid targets.A common use for disabling this is for ray interactors used for teleportation to make the teleportation interactable no longer selected when not currently pointing at it. |
| Allow Hovered Activate | Controls whether to send activate and deactivate events to interactables that this interactor is hovered over but not selected when there is no current selection. By default, the interactor will only send activate and deactivate events to interactables that it has selected. |
| Target Priority Mode | Specifies whether interactables are tracked in the interactor's valid target list. Set to None if your application doesn't use this list. |
| Hover To Select | Enable to have interactor automatically select an interactable after hovering over it for a period of time. Will also select UI if UI Interaction is also enabled. |
| Starting Selected Interactable | The interactable that this interactor automatically selects at startup (optional, may be None). |
| Parent Interactable | An optional reference to a parent interactable dependency for determining processing order of interactables. Refer to Processing interactables for more information. |
| Auto Find Parent Interactable | Automatically find a parent interactable up the GameObject hierarchy when registered with the interaction manager. Disable to manually set the object reference for improved startup performance. |
Select Action Trigger
Use the Select Action Trigger to choose different styles for how the configured Select Input control triggers the selection of an interactable object. State Change is the default option and provides the most intuitive selection behavior for typical interactions.
The Select Action Trigger options are:
| Select Action Trigger option | Description |
|---|---|
| State | A selection can be triggered as long as the user keeps Select Input control activated. For example, if a user holds down a button configured as the Select Input before hovering on an interactable, the first interactable hovered while the button remains down will become selected. |
| State Change | A selection can be triggered only during the frame in which the user activates the Select Input control. The interactable remains selected until the Select Input is released. |
| Toggle | Like State Change except the selection persists until the second time the Select Input control is activated. |
| Sticky | Like Toggle, except the selection persists until the second time the Select Input control is released. |
Note
When Select Action Trigger is set to State and the user selects an interactable set to InteractableSelectMode.Single with more than one interactor at the same time, then the selection of the interactable can be passed back and forth between the interactors each frame. This can also cause the select interaction events to fire each frame. To avoid this behavior, set Select Action Trigger to State Change, which is the default and recommended option.
Target Priority Mode
The Target Priority Mode option determines whether the interactor creates a list of priority targets every frame and how many objects are included in the list. The list of targets is available from the interactor's GetValidTargets
The Target Priority Mode options are:
| Target Priority Mode option | Description |
|---|---|
| None | This interactor does not maintain a target list. |
| Highest Priority Only | The target list contains only the highest priority interactable that is eligible for selection in the scene during the current frame. |
| All | The target list contains all of the interactables eligible for selection in the scene during the current frame. |
Tip
You should leave the Target Priority Mode set to None, its default value, unless your application code uses the target list.
Input Configuration
Configure Input Reader properties to specify what kinds of input trigger select and activate interactions.
| Property | Description |
|---|---|
| Select Input | Choose what kinds of input trigger selection of a hovered interactable. |
| Activate Input | Choose what kinds of input trigger activation of a selected interactable. |
Refer to the Input section for information about how to configure input options.
Note
You can change how the Inspector shows Input Reader properties with the Editor Settings: Input Reader Property Drawer Mode property on the XR Interaction Toolkit setting page. You can find this settings page in the Project Settings under the XR Plug-in Management section.
Interactor Filters
Configure the starting set of filters that an interactor uses to determine which interactables are eligible for interaction. All of these filter properties are optional. If you do not assign them, the interactor uses default behavior.
Refer to Interaction filters for more information about implementing filters.
| Property | Description |
|---|---|
| Starting Target Filter | Filters the list of interactables that are eligible for interaction. |
| Starting Hover Filters list | Validates which potential hover targets are eligible for hover interaction. |
| Starting Select Filters list | Validates which potential select targets are eligible for select interaction. |
Interactor Events
You can assign listener functions for interaction events in the Inspector window and in a C# class. These events apply to interactors - objects that can interact with interactables.
The UI Hover Entered and UI Hover Exited events are not available on all interactor components. Only those interactors that implement IUIHoverInteractor and enable UI Interaction with the XR UI Input Module, such as XR Poke Interactor, will have these events.
For detailed code examples showing how to subscribe to events and work with the event arguments, refer to Handle interaction events.
| Property | Description |
|---|---|
| Hover Entered | The event that is called when this interactor begins hovering over an interactable. |
| Hover Exited | The event that is called when this interactor ends hovering over an interactable. |
| Select Entered | The event that is called when this interactor begins selecting an interactable. |
| Select Exited | The event that is called when this interactor ends selecting an interactable. |
| UI Hover Entered Event | Event triggered when a UI element is hovered over by this interactor. |
| UI Hover Exited Event | Event triggered when a UI element is no longer hovered over by this interactor. |
Note
Additional events might be available to listeners you assign in C# code. Refer to the XRBaseInteractor subclass documentation for specific information.
Extend the near-far interactor
The near-far interactor is designed with modularity and extensibility in mind. You can implement custom near and far casters that adhere to the IInteractionCaster and ICurveInteractionCaster interfaces, respectively. The Sphere Interaction Caster and Curve Interaction Caster components provide the default implementations of these interfaces.
Implement the IInteractionAttachController interface to create a custom controller for manipulating the attach transform. The Interaction Attach Controller provides the default implementation for this interface and enables distance-based velocity scaling on motion to pull objects to the user from afar, with hand tracking and controller tracking support.