Active control strategy for target and origin

Through the following content, you will learn about the default display and hide strategies for objects under target and origin, and how to adjust them as needed.

Before you begin

• Read Target to understand the basic concepts, states, and lifecycle of target.
• Read XR Origin to understand the basic concepts, composition, and lifecycle of XR Origin.

Active control and control strategy types

During session runtime, target and origin undergo state changes such as tracking and loss. Through active control strategies, the display and hide behaviors of objects under target and origin can be automatically managed.

In Unity, the ActiveController component is responsible for automatically managing the GameObject.activeSelf state of target and origin objects, so that content is displayed after target is tracked or motion tracking starts tracking, and hidden before target is lost or motion tracking successfully initializes.

ActiveController provides two different active control strategies:

• ActiveWhileTracked: When tracked, the GameObject is activated (GameObject.activeSelf set to true); when tracking is lost, the GameObject is deactivated (GameObject.activeSelf set to false).
• ActiveAfterFirstTracked: Before first tracking, the GameObject is deactivated (GameObject.activeSelf set to false); once successfully tracked, the GameObject remains activated (GameObject.activeSelf set to true).

By default, TargetController uses the ActiveWhileTracked strategy, meaning that when target is tracked, target and its content are activated, and when tracking is lost, target and its content are deactivated.

By default, XROriginChildController uses the ActiveAfterFirstTracked strategy, meaning that before motion tracking successfully initializes, origin and its content are deactivated, and once motion tracking successfully initializes, origin and its content remain activated.

Selecting different active control strategies

Open the Inspector panel, select Strategy from the dropdown menu Input

Then select the desired active control strategy on the right to override the default strategy.

In scripts, you can override the default active control strategy through the OverrideStrategy property.

For example, the following code shows how to set target's active control strategy to ActiveAfterFirstTracked:

target.ActiveController.OverrideStrategy = ActiveController.Strategy.ActiveAfterFirstTracked;

Changes to the active strategy take effect immediately and update GameObject.activeSelf based on the current tracking state.

Turning off active control

If you need to completely disable active control, such as when manual control is required, you can turn off active control by disabling the ActiveController component.

In scripts, you can turn off active control by setting the ActiveController.enabled property.

target.ActiveController.enabled = false;

Changes to the enabled property take effect immediately and will no longer update GameObject.activeSelf based on tracking state. If you re-enable the ActiveController component, GameObject.activeSelf will update based on the current tracking state.