Class XRInteractionGroup

Behaviour implementation of IXRInteractionGroup. An Interaction Group hooks into the interaction system (via XRInteractionManager) and enforces that only one IXRGroupMember within the Group can interact at a time. Each Group member must be either an IXRInteractor or an IXRInteractionGroup.

Inheritance
Object
Object
Component
Behaviour
MonoBehaviour
XRInteractionGroup
Inherited Members
UnityEngine.Component.GetComponentInParent<T>(System.Boolean)
UnityEngine.Object.FindObjectsByType<T>(UnityEngine.FindObjectsSortMode)
UnityEngine.Object.FindObjectsOfType<T>(System.Boolean)
UnityEngine.Object.FindObjectsByType<T>(UnityEngine.FindObjectsInactive, UnityEngine.FindObjectsSortMode)
UnityEngine.Object.FindObjectOfType<T>(System.Boolean)
UnityEngine.Object.FindFirstObjectByType<T>()
UnityEngine.Object.FindAnyObjectByType<T>()
UnityEngine.Object.FindFirstObjectByType<T>(UnityEngine.FindObjectsInactive)
UnityEngine.Object.FindAnyObjectByType<T>(UnityEngine.FindObjectsInactive)
Namespace: UnityEngine.XR.Interaction.Toolkit
Syntax
[DisallowMultipleComponent]
[AddComponentMenu("XR/XR Interaction Group", 11)]
[HelpURL("https://docs.unity3d.com/Packages/com.unity.xr.interaction.toolkit@2.4/api/UnityEngine.XR.Interaction.Toolkit.XRInteractionGroup.html")]
[DefaultExecutionOrder(-100)]
public class XRInteractionGroup : MonoBehaviour, IXRInteractionOverrideGroup, IXRInteractionGroup, IXRGroupMember
Remarks

The member prioritized for interaction in any given frame is whichever member was interacting the previous frame if it can select in the current frame. If there is no such member, then the interacting member is whichever one in the ordered list of members interacts first.

Properties

activeInteractor

The Interactor in this Interaction Group or any of its member Groups that is currently performing interaction.

Declaration
public IXRInteractor activeInteractor { get; }
Property Value
Type Description
IXRInteractor
Implements

containingGroup

The Interaction Group that contains this member.

Declaration
public IXRInteractionGroup containingGroup { get; }
Property Value
Type Description
IXRInteractionGroup
Implements

focusInteractable

The Interactable that is currently being focused by an Interactor in this Interaction Group or any of its member Groups.

Declaration
public IXRFocusInteractable focusInteractable { get; }
Property Value
Type Description
IXRFocusInteractable
Implements

focusInteractor

The Interactor in this Interaction Group or any of its member Groups that initiated the last focus event.

Declaration
public IXRInteractor focusInteractor { get; }
Property Value
Type Description
IXRInteractor
Implements

groupName

The name of the interaction group, which can be used to retrieve it from the Interaction Manager.

Declaration
public string groupName { get; }
Property Value
Type Description
String
Implements

interactionManager

The XRInteractionManager that this Interaction Group will communicate with (will find one if null).

Declaration
public XRInteractionManager interactionManager { get; set; }
Property Value
Type Description
XRInteractionManager

startingGroupMembers

Ordered list of Interactors or Interaction Groups that are registered with the Group on Awake. All objects in this list should implement the IXRGroupMember interface and either the IXRInteractor interface or the IXRInteractionGroup interface.

Declaration
public List<Object> startingGroupMembers { get; set; }
Property Value
Type Description
List<Object>
Remarks

There are separate methods to access and modify the Group members used after Awake.

See Also

Methods

AddGroupMember(IXRGroupMember)

Adds the given Group member to the end of the ordered list of members in the Group. Causes no change if the Group member is already added.

Declaration
public void AddGroupMember(IXRGroupMember groupMember)
Parameters
Type Name Description
IXRGroupMember groupMember

The Group member to add.
Implements
Remarks

groupMember must implement either IXRInteractor or IXRInteractionGroup.

AddInteractionOverrideForGroupMember(IXRGroupMember, IXRGroupMember)

Adds overrideGroupMember as a possible interaction override for sourceGroupMember.

Declaration
public void AddInteractionOverrideForGroupMember(IXRGroupMember sourceGroupMember, IXRGroupMember overrideGroupMember)
Parameters
Type Name Description
IXRGroupMember sourceGroupMember

The Group member whose interaction can be potentially overridden by overrideGroupMember.
IXRGroupMember overrideGroupMember

The Group member to add as a possible interaction override.
Implements
Remarks

Both members must be registered with the Group. Additionally, overrideGroupMember must implement either IXRSelectInteractor or IXRInteractionOverrideGroup. This method must not create a loop in the chain of overrides for sourceGroupMember. Use the implementation of GroupMemberIsPartOfOverrideChain(IXRGroupMember, IXRGroupMember) to ensure there is no loop before adding override.

AddStartingInteractionOverride(Object, Object)

Adds overrideGroupMember to the list of Group members that are to be added as interaction overrides for sourceGroupMember on Awake. Both objects must already be included in the startingGroupMembers list. The override object should implement either the IXRSelectInteractor interface or the IXRInteractionOverrideGroup interface.

Declaration
public void AddStartingInteractionOverride(Object sourceGroupMember, Object overrideGroupMember)
Parameters
Type Name Description
Object sourceGroupMember

The Group member whose interaction can be potentially overridden by overrideGroupMember.
Object overrideGroupMember

The Group member to add as a possible interaction override.
Remarks

Use AddInteractionOverrideForGroupMember(IXRGroupMember, IXRGroupMember) to add to the interaction overrides used after Awake.

See Also

Awake()

See MonoBehaviour.

Declaration
protected virtual void Awake()

ClearGroupMembers()

Removes all Group members from the list of members.

Declaration
public void ClearGroupMembers()
Implements

ClearInteractionOverridesForGroupMember(IXRGroupMember)

Clears the set of possible interaction overrides for sourceGroupMember.

Declaration
public bool ClearInteractionOverridesForGroupMember(IXRGroupMember sourceGroupMember)
Parameters
Type Name Description
IXRGroupMember sourceGroupMember

The Group member whose interaction can no longer be overridden.
Returns
Type Description
Boolean

Returns true if there is a set of overrides for sourceGroupMember. Otherwise, returns false.
Implements
Remarks

sourceGroupMember must be registered with the Group.

ContainsGroupMember(IXRGroupMember)

Checks whether the given Group member exists in the list of members.

Declaration
public bool ContainsGroupMember(IXRGroupMember groupMember)
Parameters
Type Name Description
IXRGroupMember groupMember

The Group member to check for in the list.
Returns
Type Description
Boolean

Returns true if groupMember exists in the list. Otherwise, returns false.
Implements

GetGroupMembers(List<IXRGroupMember>)

Returns all members in the ordered list of Group members into List results.

Declaration
public void GetGroupMembers(List<IXRGroupMember> results)
Parameters
Type Name Description
List<IXRGroupMember> results

List to receive Group members.
Implements
Remarks

This method populates the list with the Group members at the time the method is called. It is not a live view, meaning Group members added or removed afterward will not be reflected in the results of this method. Clears results before adding to it.

GetInteractionOverridesForGroupMember(IXRGroupMember, HashSet<IXRGroupMember>)

Returns all members in the set of possible interaction overrides for sourceGroupMember into set results.

Declaration
public void GetInteractionOverridesForGroupMember(IXRGroupMember sourceGroupMember, HashSet<IXRGroupMember> results)
Parameters
Type Name Description
IXRGroupMember sourceGroupMember

The Group member whose overrides to get.
HashSet<IXRGroupMember> results

Set to receive override Group members.
Implements
Remarks

sourceGroupMember must be registered with the Group. This method populates the set with the Group members at the time the method is called. It is not a live view, meaning override Group members added or removed afterward will not be reflected in the results of this method. Clears results before adding to it.

GroupMemberIsPartOfOverrideChain(IXRGroupMember, IXRGroupMember)

Checks whether potentialOverrideGroupMember is either the same as sourceGroupMember or part of a chain of its override Group members and their overrides.

Declaration
public bool GroupMemberIsPartOfOverrideChain(IXRGroupMember sourceGroupMember, IXRGroupMember potentialOverrideGroupMember)
Parameters
Type Name Description
IXRGroupMember sourceGroupMember

The source Group member for the potential chain of override members.
IXRGroupMember potentialOverrideGroupMember

The Group member to check for as part of a chain of overrides.
Returns
Type Description
Boolean

Returns true if potentialOverrideGroupMember is either the same as sourceGroupMember or part of a chain of its override Group members and their overrides. Otherwise, returns false.
Implements

HasDependencyOnGroup(IXRInteractionGroup)

Checks whether the given Group is either the same as this Group or a dependency of any member Group.

Declaration
public bool HasDependencyOnGroup(IXRInteractionGroup group)
Parameters
Type Name Description
IXRInteractionGroup group

The Group to check for as a dependency.
Returns
Type Description
Boolean

Returns true if group is either the same as this Group or a dependency of this Group. Otherwise, returns false.
Implements

MoveGroupMemberTo(IXRGroupMember, Int32)

Moves the given Group member to the specified index in the ordered list of members in the Group. If the member is not in the list, this can be used to insert the member at the specified index.

Declaration
public void MoveGroupMemberTo(IXRGroupMember groupMember, int newIndex)
Parameters
Type Name Description
IXRGroupMember groupMember

The Group member to move or add.
Int32 newIndex

New index of the Group member.
Implements
Remarks

groupMember must implement either IXRInteractor or IXRInteractionGroup.

OnDestroy()

See MonoBehaviour.

Declaration
protected virtual void OnDestroy()

OnDisable()

See MonoBehaviour.

Declaration
protected virtual void OnDisable()

OnEnable()

See MonoBehaviour.

Declaration
protected virtual void OnEnable()

OnFocusEntering(FocusEnterEventArgs)

The XRInteractionManager calls this method right before the Interaction group first gains focus of an Interactable in a first pass.

Declaration
public void OnFocusEntering(FocusEnterEventArgs args)
Parameters
Type Name Description
FocusEnterEventArgs args

Event data containing the Interaction group that is initiating the focus.
Implements
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

OnFocusExiting(FocusExitEventArgs)

The XRInteractionManager calls this method right before the Interaction group loses focus of an Interactable in a first pass.

Declaration
public void OnFocusExiting(FocusExitEventArgs args)
Parameters
Type Name Description
FocusExitEventArgs args

Event data containing the Interaction group that is losing focus.
Implements
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

RemoveGroupMember(IXRGroupMember)

Removes the given Group member from the list of members.

Declaration
public bool RemoveGroupMember(IXRGroupMember groupMember)
Parameters
Type Name Description
IXRGroupMember groupMember

The Group member to remove.
Returns
Type Description
Boolean

Returns true if groupMember was removed from the list. Otherwise, returns false if groupMember was not found in the list.
Implements

RemoveInteractionOverrideForGroupMember(IXRGroupMember, IXRGroupMember)

Removes overrideGroupMember as a possible interaction override for sourceGroupMember.

Declaration
public bool RemoveInteractionOverrideForGroupMember(IXRGroupMember sourceGroupMember, IXRGroupMember overrideGroupMember)
Parameters
Type Name Description
IXRGroupMember sourceGroupMember

The Group member whose interaction can no longer be overridden by overrideGroupMember.
IXRGroupMember overrideGroupMember

The Group member to remove as a possible interaction override.
Returns
Type Description
Boolean

Returns true if overrideGroupMember was removed from the set of potential overrides for sourceGroupMember. Otherwise, returns false if overrideGroupMember was not part of the set.
Implements
Remarks

sourceGroupMember must be registered with the Group.

RemoveStartingInteractionOverride(Object, Object)

Removes overrideGroupMember from the list of Group members that are to be added as interaction overrides for sourceGroupMember on Awake.

Declaration
public bool RemoveStartingInteractionOverride(Object sourceGroupMember, Object overrideGroupMember)
Parameters
Type Name Description
Object sourceGroupMember

The Group member whose interaction can no longer be overridden by overrideGroupMember.
Object overrideGroupMember

The Group member to remove as a possible interaction override.
Returns
Type Description
Boolean

Returns true if overrideGroupMember was removed from the list of potential overrides for sourceGroupMember. Otherwise, returns false if overrideGroupMember was not part of the list.
Remarks

Use RemoveInteractionOverrideForGroupMember(IXRGroupMember, IXRGroupMember) to remove from the interaction overrides used after Awake.

See Also

Reset()

See MonoBehaviour.

Declaration
[Conditional("UNITY_EDITOR")]
protected virtual void Reset()

Events

registered

Calls the methods in its invocation list when this Interaction Group is registered with an Interaction Manager.

Declaration
public event Action<InteractionGroupRegisteredEventArgs> registered
Event Type
Type Description
Action<InteractionGroupRegisteredEventArgs>
Implements
Remarks

The InteractionGroupRegisteredEventArgs passed to each listener is only valid while the event is invoked, do not hold a reference to it.

See Also

unregistered

Calls the methods in its invocation list when this Interaction Group is unregistered from an Interaction Manager.

Declaration
public event Action<InteractionGroupUnregisteredEventArgs> unregistered
Event Type
Type Description
Action<InteractionGroupUnregisteredEventArgs>
Implements
Remarks

The InteractionGroupUnregisteredEventArgs passed to each listener is only valid while the event is invoked, do not hold a reference to it.

See Also

Explicit Interface Implementations

IXRGroupMember.OnRegisteringAsGroupMember(IXRInteractionGroup)

An IXRInteractionGroup calls this method just after this member has been added to the Group's list or just after the Group has registered with the XRInteractionManager. This method is called just before the member is re-registered with the Interaction Manager so that it can be registered as being part of a Group.

Declaration
void IXRGroupMember.OnRegisteringAsGroupMember(IXRInteractionGroup group)
Parameters
Type Name Description
IXRInteractionGroup group

The Interaction Group that this member is now a part of.
Implements
Remarks

Implementations of this method should ensure that containingGroup returns group after this method is called.

IXRGroupMember.OnRegisteringAsNonGroupMember()

An IXRInteractionGroup calls this method just after this member has been removed from the Group's list or before the Group unregisters with the XRInteractionManager. This method is called just before the member is re-registered with the Interaction Manager so that it can be registered as being not part of a Group.

Declaration
void IXRGroupMember.OnRegisteringAsNonGroupMember()
Implements
Remarks

Implementations of this method should ensure that containingGroup returns null after this method is called.

IXRInteractionGroup.OnBeforeUnregistered()

The XRInteractionManager calls this method just before this Interaction Group is unregistered from it.

Declaration
void IXRInteractionGroup.OnBeforeUnregistered()
Implements
Remarks

This is where the Group should re-register its members with the Interaction Manager so that they are registered as not belonging to a Group.

See Also

IXRInteractionGroup.OnRegistered(InteractionGroupRegisteredEventArgs)

The XRInteractionManager calls this method when this Interaction Group is registered with it.

Declaration
void IXRInteractionGroup.OnRegistered(InteractionGroupRegisteredEventArgs args)
Parameters
Type Name Description
InteractionGroupRegisteredEventArgs args

Event data containing the Interaction Manager that registered this Interaction Group.
Implements
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

IXRInteractionGroup.OnUnregistered(InteractionGroupUnregisteredEventArgs)

The XRInteractionManager calls this method when this Interaction Group is unregistered from it.

Declaration
void IXRInteractionGroup.OnUnregistered(InteractionGroupUnregisteredEventArgs args)
Parameters
Type Name Description
InteractionGroupUnregisteredEventArgs args

Event data containing the Interaction Manager that unregistered this Interaction Group.
Implements
Remarks

args is only valid during this method call, do not hold a reference to it.

See Also

IXRInteractionGroup.PreprocessGroupMembers(XRInteractionUpdateOrder.UpdatePhase)

The XRInteractionManager or containing IXRInteractionGroup calls this method to update the Group and its members before interaction events occur.

Declaration
void IXRInteractionGroup.PreprocessGroupMembers(XRInteractionUpdateOrder.UpdatePhase updatePhase)
Parameters
Type Name Description
XRInteractionUpdateOrder.UpdatePhase updatePhase

The update phase during which this method is called.
Implements
Remarks

Please see the XRInteractionManager and XRInteractionUpdateOrder.UpdatePhase documentation for more details on update order.

See Also

IXRInteractionGroup.ProcessGroupMembers(XRInteractionUpdateOrder.UpdatePhase)

The XRInteractionManager or containing IXRInteractionGroup calls this method to update the Group and its members after interaction events occur.

Declaration
void IXRInteractionGroup.ProcessGroupMembers(XRInteractionUpdateOrder.UpdatePhase updatePhase)
Parameters
Type Name Description
XRInteractionUpdateOrder.UpdatePhase updatePhase

The update phase during which this method is called.
Implements
Remarks

Please see the XRInteractionManager and XRInteractionUpdateOrder.UpdatePhase documentation for more details on update order.

See Also

IXRInteractionGroup.UpdateGroupMemberInteractions()

The XRInteractionManager calls this method to update interactions for this Group's members. This is where interaction events occur for any IXRInteractor member.

Declaration
void IXRInteractionGroup.UpdateGroupMemberInteractions()
Implements
Remarks

The implementation of this method should call UpdateGroupMemberInteractions(IXRInteractor, out IXRInteractor).

IXRInteractionGroup.UpdateGroupMemberInteractions(IXRInteractor, out IXRInteractor)

Updates interactions for this Group's members, given an Interactor that has already been prioritized for interaction. This is where interaction events occur for any IXRInteractor member.

Declaration
void IXRInteractionGroup.UpdateGroupMemberInteractions(IXRInteractor prePrioritizedInteractor, out IXRInteractor interactorThatPerformedInteraction)
Parameters
Type Name Description
IXRInteractor prePrioritizedInteractor

The Interactor that has already been prioritized for interaction. If not null, this prevents all other members in this Group from interacting.
IXRInteractor interactorThatPerformedInteraction

The Interactor in this Group or any of its member Groups that performed interaction as a result of this method call. This will be null if no Interactor performed interaction.
Implements
Remarks

The implementation of this method should call this method on each member that is an IXRInteractionGroup. After this method is called, activeInteractor should return the same reference as interactorThatPerformedInteraction.

IXRInteractionOverrideGroup.ShouldAnyMemberOverrideInteraction(IXRInteractor, out IXRSelectInteractor)

Checks whether any member of the Group should override the interactions of interactingInteractor. An interactor should only override if it is capable of selecting any interactable that interactingInteractor is interacting with. If multiple Group members are capable of overriding, only the highest priority one should override.

Declaration
bool IXRInteractionOverrideGroup.ShouldAnyMemberOverrideInteraction(IXRInteractor interactingInteractor, out IXRSelectInteractor overridingInteractor)
Parameters
Type Name Description
IXRInteractor interactingInteractor
IXRSelectInteractor overridingInteractor

The interactor that should override interaction.
Returns
Type Description
Boolean

Returns true if any member of the Group should override the interactions of interactingInteractor. Otherwise, returns false.
Implements
Remarks

The implementation of this method should call this method on each Group member that is an IXRInteractionOverrideGroup.

IXRInteractionOverrideGroup.ShouldOverrideActiveInteraction(out IXRSelectInteractor)

Checks whether the Group should end the interactions of the activeInteractor and instead prioritize an override interactor for interaction. An interactor should only override if it exists in the set of override Group members for the active member and is capable of selecting any interactable that activeInteractor is interacting with. If multiple Group members are capable of overriding, only the highest priority one should override.

Declaration
bool IXRInteractionOverrideGroup.ShouldOverrideActiveInteraction(out IXRSelectInteractor overridingInteractor)
Parameters
Type Name Description
IXRSelectInteractor overridingInteractor

The interactor that should override interaction.
Returns
Type Description
Boolean

Returns true if the Group should end the interactions of the activeInteractor and instead prioritize an override interactor for interaction. Otherwise, returns false.
Implements
Remarks

The implementation of UpdateGroupMemberInteractions(IXRInteractor, out IXRInteractor) should call this method at the start to determine whether overridingInteractor should override the pre-prioritized interactor. The implementation of this method should call ShouldAnyMemberOverrideInteraction(IXRInteractor, out IXRSelectInteractor) on each override Group member that is an IXRInteractionOverrideGroup.

Extension Methods