Unity MR Part 2: Session Component

👀 Stumbled here on accident? Start with the introduction!

📚 In this article, you'll discover the concept of a session in MR and how to apply it in Unity. We'll discuss differences in sessions in ARFoundation and OpenXR: Meta, set up our Session GameObject, and conduct tests on the Meta Quest 3. This exploration will provide a comprehensive understanding of session management in Unity for MR applications, especially for the Meta Quest 3 platform.

ℹ️ If you find yourself facing any difficulties, remember that you can always refer to or download the code from our accompanying GitHub repository

A session refers to the period during which the app is actively tracking and integrating real-world and virtual environments, handling user interactions, and maintaining continuity in the mixed reality experience.

About Session in ARFoundation

In AR Foundation, the AR Session component is crucial for controlling the lifecycle of an AR experience on the target platform. It represents an instance of AR, and other features like plane detection can be independently enabled or disabled within this framework. The AR Session component is responsible for tracking features in the environment. When this component is disabled, the system stops tracking these features, but if re-enabled later, it attempts to recover and maintain the previously detected features. It's important to note that multiple AR Session components in the same scene can conflict with each other, so it's recommended to add at most one AR Session component to a scene.

The AR Session component also checks for device support. Since some platforms have built-in AR capabilities, while others may require on-demand installation of AR software or might not support AR at all, it's vital for applications to detect support for AR Foundation to provide alternative experiences when AR is not supported. This might involve checking a remote server for software availability.

The AR Session state can be monitored using ARSession.state, and you can subscribe to the ARSession.stateChanged event to receive callbacks when the state changes. This state includes various statuses like None, Unsupported, CheckingAvailability, NeedsInstall, Installing, Ready, SessionInitializing, and SessionTracking, each indicating different stages of AR session readiness and functionality.

About Session in OpenXR: Meta

In the context of OpenXR: Meta, the Session is a supplement to the AR Foundation Session manual, focusing on the unique platform-specific behavior of the Meta Quest. This includes a feature called Scene Capture, where, unlike other AR platforms, OpenXR: Meta does not dynamically detect trackables at runtime. Instead, it queries the device's Room Setup data and returns information stored in the Scene Model. During scene capture, users can label surfaces and objects in their environment, like walls and furniture. Once the scene capture is complete, the Scene Model is saved to the device and persists across applications and sessions.

The lifecycle of scene capture in OpenXR: Meta involves several phases: initiating scene capture, suspension of the app during capture, completion of scene capture by the user, and resumption of the app post-capture.

These features highlight the comprehensive nature of AR Session components in managing and maintaining AR experiences in Unity's AR Foundation and OpenXR: Meta, showcasing the advancements and unique aspects of AR technology in different platforms.

Adding the Session component to the scene

Create an Empty GameObject

1. First, open your Unity project.
2. In the Unity editor, go to the Hierarchy panel.
3. Right-click in the Hierarchy panel and select "Create Empty" to create a new GameObject and name it Session.
4. This GameObject will act as a container for your AR components.

Add the AR Session Script

1. With the new GameObject selected, go to the Inspector panel.
2. Click on "Add Component".
3. Search for “AR Session” and add it to your GameObject.
4. The AR Session component is essential for managing the AR experience, including tracking and session management.

Initially, you'll be using the default settings of the AR Session component. These defaults are usually sufficient for basic AR experiences.

ℹ️ You might observe that we are using a custom layout in the Unity Editor, which means that the screenshots provided may not exactly match the appearance of your Editor. Keep in mind that while the visual layout may vary, the fundamental features and functions of Unity remain consistent across different customizations.

Check for device support

Select the Session GameObject in your hierarchy. Create a new script DeviceSupport via Add Component.

Let's verify if the connected device is AR-capable. As this course focuses on the Meta Quest 3, AR support is typically guaranteed. By setting attemptUpdate = true, the device will attempt to install AR software if feasible. However, the availability of this feature is dependent on the platform.

DeviceSupport looks as follows:

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.XR.ARFoundation;

namespace Taikonauten.Unity.ArticleSeries
{
    public class DeviceSupport : MonoBehaviour
    {
        \[SerializeField\] ARSession session;

        IEnumerator Start()
        {
            session.attemptUpdate = true;

            if (session == null)
            {
                Debug.LogError("DeviceSupport -> Start(): session is null");

                yield break;
            }

            if ((ARSession.state == ARSessionState.None) ||
                (ARSession.state == ARSessionState.CheckingAvailability))
            {
                Debug.Log("DeviceSupport -> Start(): check availability");

                yield return ARSession.CheckAvailability();
            }

            if (ARSession.state == ARSessionState.Unsupported)
            {
                // Start some fallback experience for unsupported devices
                Debug.Log("DeviceSupport -> Start(): unsupported device");
            }
            else
            {
                // Start the AR session
                Debug.Log("DeviceSupport -> Start(): start AR session");

                session.enabled = true;
            }
        }
    }
}

To prevent any potential naming conflicts, we will adopt the namespace Taikonauten.Unity.ArticleSeries for all our scripts moving forward.

ℹ️ This practice will ensure a clear and organized code structure, helping to distinguish our script elements effectively within the project. Using a specific namespace like Taikonauten.Unity.ArticleSeries is a best practice in software development for maintaining code clarity and avoiding clashes with other code entities.

In the Unity Editor, choose Session (AR Session) as the value for the Session field for your newly created script. Your Session GameObject should now resemble the appearance shown in the following screenshot.

To maintain an organized project structure, create a Scripts folder within the Assets directory in the Project window. Then, move the DeviceSupport Script into this new folder. This approach helps in keeping your project tidy and ensures that all scripts are conveniently located in a dedicated folder.

Testing the app

To run a Unity project on your Meta Quest 3 using the Link Cable, follow these steps:

1. Connect the Meta Quest 3 to Your PC

Use the Link Cable to connect your Meta Quest 3 headset to your computer.

2. Enable Oculus Link on Your Headset

Put on your Meta Quest 3 headset and enable Oculus Link when prompted. This will connect your headset to the Unity Editor running on your PC.

3. Press the Play Button in Unity

Go back to the Unity Editor on your PC and press the 'Play' button. This will start running your Unity project directly in your Meta Quest 3 headset.

ℹ️ If you're using a Mac, the standard approach might not work. Instead, use File → Build and Run while the Meta Quest 3 is connected to your computer. We cover this process in the article Enter MR, specifically in the Testing the App section

4. View the Output in Your Headset

You should now see the Unity project running in your headset as seen in the next screenshot.

If you encounter any issues, ensure that your Meta Quest 3 is set up correctly with your PC, the Oculus software is installed and up to date, and your Unity project is configured for Oculus VR development.

⚠️ No active UnityEngine.XR.ARSubsystems.XRSessionSubsystem is available. This feature is either not supported on the current platform, or you may need to enable a provider in Project Settings > XR Plug-in Management.
UnityEngine.XR.ARFoundation.ARSession:OnEnable () (at ./Library/PackageCache/com.unity.xr.arfoundation@6.0.0-pre.4/Runtime/ARFoundation/ARSession.cs:331)

The message you're seeing in the Unity Editor Console is a warning that can be safely ignored. It's indicating that the XRSessionSubsystem is only available in built applications for their specific build targets, which is Android in this case. This means that the XRSessionSubsystem, a component used for handling XR (Extended Reality) sessions, won't be available or functional within the Unity Editor itself, but it will work as expected once the application is built and deployed to the Meta Quest 3.

Next article

In our upcoming article, we will delve into the integral aspects of the Camera Component in Unity, especially in the context of AR and VR development. The Camera Component is a fundamental part of any immersive experience, acting as the eyes of the user in the virtual world. We'll explore its capabilities, how it can be configured and manipulated to suit our needs.