AR Session component

Use the AR Session component to control the lifecycle of AR in your project.

The ARSession component controls the lifecycle of an AR experience. On non-OpenXR platforms, the ARSession component enables or disables AR on the target platform.

Note

On OpenXR platforms (Meta Quest and Android XR), AR Foundation can't create or destroy the AR session. On these platforms, enabling or disabling the ARSession has no effect on enabling or disabling AR.

Introduction to the AR session

A session refers to an instance of AR. While other features like plane detection can be independently enabled or disabled, the session controls the lifecycle of all AR features.

Enabling or disabling the ARSession on non-OpenXR platforms starts or stops the session, respectively. When you disable the AR Session components, the system no longer tracks features in its environment. Then if you enable it at a later time, the system attempts to recover and maintain previously detected features.

Add the AR Session component

If you're starting your project from an XR template or an AR Foundation sample, your project will already contain an ARSession in every scene.

To manually add the ARSession component to your scene, right click in the Hierarchy window, and select XR > AR Session.

Important

Adding multiple instances of the same type of manager component to a scene can cause conflicts. Don't enable more than one of the same manager in your scene at a time.

Component reference

AR Session component.

You can configure the following settings in the Inspector window on supported platforms:

Property	Description
Attempt Update	If enabled, the session will attempt to update a supported device if its AR software is out of date.
Match Frame Rate	If enabled, the Unity frame will be synchronized with the AR session. Otherwise, the AR session will be updated independently of the Unity frame.

Match frame rate

If you enable Match Frame Rate, the AR Session component configures the following settings:

1. Blocks each render frame until the next AR frame is ready.
2. Sets the target frame rate to the session's preferred update rate.
3. Disables VSync.

Note

These settings aren't reverted when you disable the ARSession.

Session state

It's important for your app to understand the AR Session state. All other AR Features depend on the AR Session and can't function properly until the session is tracking.

You can use ARSession.state to get the current session state. You can also subscribe to the ARSession.stateChanged event to receive a callback when the state changes. The following table lists all possible session states:

Session state	Description
None	AR has not been initialized and availability is unknown. You can call CheckAvailability to check availability of AR on the device.
Unsupported	The device does not support AR.
CheckingAvailability	The session subsystem is currently checking availability of AR on the device. The CheckAvailability coroutine has not yet completed.
NeedsInstall	The device supports AR, but requires additional software to be installed. If the provider supports runtime installation, you can call Install to attempt installation of AR software on the device.
Installing	AR software is currently installing. The Install coroutine has not yet completed.
Ready	The device supports AR, and any necessary software is installed. This state will automatically change to either SessionInitializing or SessionTracking.
SessionInitializing	The AR session is currently initializing. This usually means AR is running, but not yet tracking successfully.
SessionTracking	The AR session is running and tracking successfully. The device is able to determine its position and orientation in the world. If tracking is lost during a session, this state may change to SessionInitializing.