Interactor
Interactor is a component in OctoXR that is responsible for finding and tracking objects that it can interact with in some way and to also update interaction and hover states of all the objects that it currently hovers over and interacts with. Usually it is attached to an object that represents user's hand in the scene. It is configured using following properties:
Hover Tracker - Object of interface type IInteractionHoverTracker. Its function is to find Interactables the Interactor could potentially start interacting with, via IInteractionHoverTracker.GetInteractionHoveringObjects method. All found Interactables will first enter the hover state if they satisfy other additional conditions. Any Interactable that is currently hovered by the Interactor and not returned by the Hover Tracker is immediately stopped being hovered. This property appears in Unity editor as a drop-down with two options - Object and Managed. When set to Object, only Unity object instances (objects inheriting from UnityEngine.Object, i.e any custom MonoBehaviour or ScriptableObject) that implement IInteractionHoverTracker interface can be assigned to it. On the other hand, if set to Managed, then regular class instances can be assigned via the second drop-down that appears once the property is set to Managed. That other drop-down will list all non-Unity object types that implement the required interface (IInteractionHoverTracker). Many other properties in OctoXR, including several that are listed below, appear and function the same way.
Hover Start Indicator - Object of interface type IInteractionHoverIndicator. It is used to determine which of the Interactables obtained from Hover Tracker can actually be hovered by the Interactor (using IInteractionHoverIndicator.IsInteractionHoveringObject method). This property is optional; if left unassigned, then all Interactables returned by Hover Tracker are Implicitly considered as possible to start being hovered by the Interactor.
Interaction Start Indicator - Object of interface type IInteractionActivityIndicator. It is used to determine which of the Interactables the Interactor is hovering can start being interacted with (using IInteractionActivityIndicator.CanInteractionWithObjectStartOrContinue method). This must be assigned, otherwise the Interactor will never be able to interact with any Interactable.
Interaction End Indicator - Object of interface type IInteractionActivityIndicator. It is used to determine whether an Interactable the Interactor is interacting with should end being interacted with (using IInteractionActivityIndicator.CanInteractionWithObjectStartOrContinue method). Essentially, this functions the same way as Interaction Start Indicator, only in the opposite direction - if IInteractionActivityIndicator.CanInteractionWithObjectStartOrContinue method returns false for an Interactable, then interaction with that Interactable ends and its state is demoted from interacting to hovering. This property is optional; if left unassigned, then Interaction Start Indicator is used for preceding functionality.
Hover End Indicator - The same type and similar role as Hover Start Indicator, its relationship with it is equivalent to the relationship between Interaction End Indicator and Interaction Start Indicator, but used in the context of evaluating hovering state of an Interactable that is hovered by the Interactor. Also optional, Hover Start Indicator is used instead, if Hover Start Indicator is assigned. Note that if any Interactable hovered by the Interactor is no longer returned by Hover Tracker, then hovering over that Interactable ends regardless of values assigned to this and Hover Start Indicator properties.
Mode - Property of enumeration type InteractionMode, specifies the number of Interactables the Interactor can hover and interact with. Interactor operates with the following predefined modes:
SingleHoverAndInteraction - In this mode Interactor can hover only one Interactable and also interact with only one at any given time. If the Interactor interacts with an Interactable, then it can't hover any other Interactable, so Hover Tracker and Hover Start/End Indicators described previously will not be used as long as the current interaction is in progress. This is the usual default mode for an Interactor used throughout OctoXR.
MultipleHoversSingleInteraction - In this mode Interactor can hover multiple Interactables (no limits) at the same time, but interact with only one. However, once the Interactor starts interacting with an Interactable, it won't be able to hover any other Interactable as long as the current interaction is in progress.
MultipleHoversAndInteractions - In this mode Interactor can constantly hover and interact with any number of Interactables at any time.
Other then this property, Interactor is limited in number of Interactables it can hover and interact with via Hover Tracker property as well - if Hover Tracker only ever returns one Interactable, then Interactor will never hover and interact with more than one.
Specifications - List of InteractorSpecification-derived object types. These are mainly used by various InteractionControllers - each specific type of InteractionController in OctoXR has its own specific InteractorSpecification defined which can be added to this list. It is used by the corresponding InteractionController to store certain properties associated with the Interactor and are required by the controller to drive the behavior of the object interacting with the Interactor. More on specific InteractorSpecifications can be found in Interaction Controller section.
Finally, Interactor defines multiple events that are triggered on various hover/interaction state transitions. These can be used to execute custom logic when interactor starts/stops hovering/interacting with an Interactable:
On Start Hovering - Triggered when Interactor starts hovering over any Interactable, but only when it wasn't already hovering any Interactable, i.e. triggered on first hover start.
On Start Hovering Interactable (Interactable) - Triggered when Interactor starts hovering over an Interactable (which is passed to event handlers as event argument). This is triggered for each distinct Interactable the Interactor starts hovering. This event will fire immediately after On Start Hovering if the Interactable is the only Interactable being hovered by the Interactor.
On Start Interacting - Triggered when Interactor starts interacting with any Interactable, but only when it wasn't already interacting with any Interactable, i.e. triggered on first interaction start.
On Start Interacting With Interactable (Interactable) - Triggered when Interactor starts interacting with an Interactable (which is passed to event handlers as event argument). This is triggered for each distinct Interactable the Interactor starts interacting with. This event will fire immediately after On Start Interacting if the Interactable is the only Interactable being interacted with by the Interactor.
On End Interacting With Interactable (Interactable) - Triggered when Interactor stops interacting with an Interactable (which is passed to event handlers as event argument). This is triggered for each distinct Interactable the Interactor stops interacting with.
On End Interacting - Triggered when Interactor stops interacting with the last Interactable it was interacting with.
On End Hovering Interactable (Interactable) - Triggered when Interactor stops hovering over an Interactable (which is passed to event handlers as event argument). This is triggered for each distinct Interactable the Interactor stops hovering.
On End Hovering - Triggered when Interactor stops hovering the last Interactable it was hovering.
Interactor defines various methods that can be used mostly for obtaining the hover and interaction state of Interactor as well as the Interactables being hovered and/or interacted with. Additionally, it offers certain methods to explicity stop interactions/hovering:
bool StopHovering() - Stops hovering all Interactables that are currently hovered by Interactor. Returns true if the Interactor was hovering any Interactable when this method was called, false otherwise.
bool StopHoveringInteractable(Interactable interactable) - Stops hovering the Interactable specified via method argument. Interactables will transition from interacting to hovering state for the Interactor. Returns true if the Interactor was indeed hovering the specified Interactable when this method was called, false otherwise.
bool StopInteracting() - Stops interacting with all Interactables that the Interactor is currently interacting with. Returns true if the Interactor was interacting with any Interactable when this method was called, false otherwise.
bool StopInteractingWithInteractable(Interactable interactable) - Stops interacting with the Interactable specified via method argument. Specified Interactable will transition from interacting to hovering state for the Interactor. Returns true if the Interactor was indeed interacting with the specified Interactable when this method was called, false otherwise.
void StopInteractingAndHovering() - Causes the Interactor to stop all interactions and hovers. All Interactables the Interactor is interacting with will immediately stop being hovered as well.
void StopInteractingWithAndHoveringInteractable(Interactable interactable) - Causes the Interactor to stop interacting and/or hovering the Interactable specified by method argument.
Also note that disabling the Interactor will also stop all interactions and hovering performed by it immediately.
Usually there is no need to define a more specific Interactor type by deriving a class from it, though it can be done. For example, in order to implement custom InteractionController, one must derive from generic version of InteractionController class - InteractionController<TInteractor, TInteractable>. InteractionController is intended to drive the interaction behavior of an object depending on the exact type of Interactable and Interactor that are interacting with each other. Keep in mind however that the Interactor does not control the type of Interactables it can hover and interact with, this is governed by Hover Tracker and Hover/Interaction Start/End Indicators - in OctoXR these objects are implemented to deal with specific types of Interactables.
Last updated