Automatically switch Unity XR objects in Unity scenes

Unity's XR components (including AR Foundation) have limited device support. To use AR Foundation on supported devices while enabling AR functionality on a wide range of other devices, EasyAR provides the ability to automatically switch Unity XR objects. The following describes the changes made to scene objects and how to use this feature.

Before you begin

• Read EasyAR's Support for Unity XR Framework to understand EasyAR's support for the Unity XR framework and when you might consider using AR Foundation.
• Ensure the scene has been configured as described in AR Foundation Scene Setup and Usage in EasyAR Projects, with AR Foundation's ARSession and XROrigin added.

Feature description

Since Unity's AR Foundation is implemented on mobile devices using ARCore and ARKit, it can only be used on a limited number of devices, especially on many domestic Android phones where it is not supported. Therefore, it is generally recommended to enable AR Foundation and related functional scripts only on supported devices. The automatic switching of Unity XR objects implements this operation, primarily designed for mobile AR, and the functionality will be disabled by default on headsets.

When the full functionality is enabled,

• In the editor, easyar.ARSession will disable UnityEngine.XR.ARFoundation.ARSession.
• At runtime, easyar.ARSession will disable all Unity XR Core components and AR Foundation components during Awake().
• At runtime, if the selected FrameSource inherits from ARFoundationFrameSource or is an ExternalDeviceFrameSource that implements the XROrigin origin, the disabled Unity XR Core components and AR Foundation components will be enabled during easyar.ARSession.StartSession() (those not disabled by EasyAR will not be enabled). If other FrameSource is selected, all Unity XR Core components and AR Foundation components will be disabled during easyar.ARSession.StartSession().
• At runtime, all Unity XR Core components and AR Foundation components will be disabled during easyar.ARSession.StopSession(bool).

By default, the functionality is enabled under the following conditions,

• Enabled on Windows/Mac.
• When the switcher starts, if the loader for mobile AR (ARKit/ARCore) is active, it is enabled.
• When the switcher starts, if there are other loaders besides mobile AR (ARKit/ARCore) but none of them are active, it is disabled.

Note

Components of the XR Interaction Toolkit are not controlled by this feature, but their usability in EasyAR has not been verified. Theoretically, features that only use the Unity.XR.CoreUtils.XROrigin GameObject and its Camera should work normally. If abnormal behavior occurs, you can try setting ARSession.ARCenterMode to ARSession.ARCenterMode.SessionOrigin. If the functionality still does not work properly, you will need to implement custom control for XR Interaction Toolkit components, disabling related components when the FrameSource does not inherit from ARFoundationFrameSource.

Configuration method

This feature can be enabled or disabled through the options in Project Settings > EasyAR > Sense > Unity XR > Unity XR Auto Switch.

The options in the figure configure the behavior as follows:

• Editor: Editor mode options
  • Disable AR Session: When easyar.ARSession exists, disable UnityEngine.XR.ARFoundation.ARSession during editing.
• Player: Runtime mode options
  • Enable: Enable runtime control. Note: When this option is turned off, components disabled in edit mode will not be restored at runtime.
  • Enable If Desktop: Enable on Windows/Mac.
  • Enable If Mobile AR On Startup: When the switcher starts, if the loader for mobile AR (ARKit/ARCore) is active, enable it. Typically, this option requires Initialize XR on Startup in Project Settings > XR Plug-in Management to be selected.
  • Disable If Non Mobile AR Post Startup: When the switcher starts, if there are other loaders besides mobile AR (ARKit/ARCore) but none of them are active, disable it. Typically, this option is used when Initialize XR on Startup in Project Settings > XR Plug-in Management is not selected.
  • Restore AR Session When Disabled: When the feature is disabled, restore (enable) all disabled UnityEngine.XR.ARFoundation.ARSession (regardless of whether it was disabled by EasyAR). This option is typically used to restore components disabled during editing.

Use custom control methods

If you need to customize the switching of these components, or if EasyAR's behavior interferes with the normal operation of certain components, you need to ensure that these options are turned off and customize the component switching according to the following basic rules:

1. Disable UnityEngine.XR.ARFoundation.ARSession in the editor (it executes earlier than all other scripts in the execution sequence)
2. Disable all Unity XR Core components, AR Foundation components, and related components or features that need to be controlled before AR Foundation starts working
3. If easyar.ARSession.Assemble() selects ARCoreARFoundationFrameSource or ARKitARFoundationFrameSource during the process, enable all previously disabled components or features. This needs to be completed before StartSession() is finished. It is generally recommended to complete this in the easyar.ARSession.AssembleUpdate event response
4. If other FrameSource is selected during the easyar.ARSession.Assemble() process, keep it unchanged

Related topics

• Motion tracking and EasyAR features