Configuring your Unity Project for XR

To configure your Unity Project for XR, follow these steps:

1. Open the Project Settings window (menu: Edit > Project Settings), and select XR Plug-in Management.
2. Click Install XR Plug-in Management if the package hasn’t been installed already. You can also install it from the Package Manager window.
3. After installation completes, select a Plug-inA set of code created outside of Unity that creates functionality in Unity. There are two kinds of plug-ins you can use in Unity: Managed plug-ins (managed .NET assemblies created with tools like Visual Studio) and Native plug-ins (platform-specific native code libraries). More info
   See in Glossary Provider to enable it for the corresponding build target. To do this:
   1. Select a build target (for example, Android).
   2. Select the checkbox to the left of each plug-in you want to use for that build target.
4. After a plug-in loads, it displays in the left-hand navigation, under XRAn umbrella term encompassing Virtual Reality (VR), Augmented Reality (AR) and Mixed Reality (MR) applications. Devices supporting these forms of interactive applications can be referred to as XR devices. More info
   See in Glossary Plug-in Management. Click the plug-in to configure its settings for each build target.
5. To set up tracking, from Unity’s main menu, go to GameObject > XR > Add XR Rig.

Notes:

• Selecting an XR plug-in provider enables that provider for the corresponding build target. Unity automatically installs the plug-in package if it’s not already present.
• Disabling plug-ins doesn’t automatically uninstall existing packages. Uninstall provider plug-ins from the Package Manager.
• For a list of third-party plug-ins, see Getting Started with VR Development.

Setting up tracking in the XR plug-in framework

Implicit cameraA component which creates an image of a particular viewpoint in your scene. The output is either drawn to the screen or captured as a texture. More info
See in Glossary tracking, used in Unity versions prior to 2019.3, has been removed in the new XR plug-in framework. Implicit tracking worked for simple, HMD-only applications, but wasn’t as intuitive when used in correlation with controllers and other interactions.

To make sure XR tracking is properly configured with the XR plug-in framework, follow the steps below.

Starting from a new Scene

The instructions below apply if you start from a new SceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info
See in Glossary, or from a Scene which meets the following conditions:

• There is only one Camera in the Scene, and that Camera is tagged as the Main Camera.
• The Camera in the Scene is at the root of the hierarchy.

From Unity’s main menu, go to GameObject > XR > Add XR Rig. This attempts to transform your new Scene into a Scene that correctly supports the XR Plug-in Framework.

If you don’t see any errors in the console log, you should now be able to click Play in your Scene, and see the Camera track against the device you’ve configured in the XR Plug-in Management package.

If Unity can’t migrate your Scene correctly, an error displays in the console log. Follow the instructions in the Starting from an existing Scene section below.

Starting from an existing Scene

Migrating from an existing Scene has additional steps compared to migrating an empty Scene. As a result, there are different options depending on how your Scene is configured. The overall goal is to have the Scene track in the same way as it did before migrating to the XR Plug-in Framework.

Identify your Scene type

Find the Camera in your Scene which is tagged as the Main Camera. Unity uses this Camera to render to the HMD or other main device.

If the Main Camera GameObjectThe fundamental object in Unity scenes, which can represent characters, props, scenery, cameras, waypoints, and more. A GameObject’s functionality is defined by the Components attached to it. More info
See in Glossary:

• Is at the root of your Project’s hierarchy, follow the steps for Migrating a simple Scene.
• Is not at the root of your Project’s hierarchy, follow the steps for Migrating a complex Scene.

Migrating a simple Scene

To migrate a simple Scene, follow the steps below.

1. Create an instance of the XR Rig Prefab.

Migrating a Camera that was previously at the root of the Scene hierarchy allows you to swap the existing Camera to an XR Rig by instancing the XR Rig PrefabAn asset type that allows you to store a GameObject complete with components and properties. The prefab acts as a template from which you can create new object instances in the scene. More info
See in Glossary that this package contains.

You can find this Prefab in the Packages/XR Legacy Input Helpers/Prefabs folder. Drag the Prefab into your Scene hierarchy to create a new instance of it.

2. Move the XR Rig to match the Camera’s location.

Now that you have an instance of the XR Rig Prefab, you need to configure the XR Rig GameObject so the resulting Camera positions will be correct when your application starts.

Change the position and rotation of the XR Rig GameObject so it matches the position of the current Main Camera. If you’re applying a scale transformation to the Main Camera, make sure that you also apply this scale to the XR Rig GameObject. If you scale the XR Rig, it’s highly recommended to use a uniform scale across all three axes.

3. Replicate the position change, if necessary.

If the Main Camera in your non-migrated Scene is above the floor (its Y component is > 0.0f), you need to replicate this position change. You can do this in a few different ways, depending on what the original position the change was intended to replicate.

3.1 - Uplift to simulate the height of the user

If the previous Main Camera was raised above the floor to simulate the height of the user and the application uses a Device Tracking Origin (sometimes called “Stationary” Tracking Mode), the Camera Offset component performs this additional uplift. Otherwise, see the next section.

To configure the Camera to have a vertical uplift when the application is being used in a Device Tracking Origin mode, set the following options on the Camera Offset component on the XR Rig GameObject:

Option	Value
Requested Tracking Mode	Device
Camera Y Offset	Set this option to the height at which the existing Main Camera is raised to simulate user height.

After you configure these options, change the XR Rig GameObject’s Y Position to be what you would consider as the “floor” in your application (usually 0.0f). The Camera Offset component adds any additional uplift as needed.

3.2 - Uplift indicates camera position

If your non-migrated Scene uses Floor Tracking Origin (historically referred to as “Room Scale” Tracking Mode), and the position of the Main Camera represents the user’s starting point without including their height (that is, the camera is effectively on the logical “floor”), follow these steps to migrate your Scene correctly:

• Move the XR Rig to match the Main Camera’s current position and rotation in Unity world space.
• If the application is using a Floor Tracking Origin, set the Requested Tracking Mode on the Camera Offset component to Floor. This ensures that the camera has the correct vertical offset.
• If the application isn’t using a Floor Tracking Origin, set the Requested Tracking Mode on the Camera Offset component to Default. This applies the correct behavior regardless of the device tracking mode the application starts with.
• If you were previously using a different component to move the Camera vertically and handle the difference between Device and Floor tracking origins, you might need to disable or modify this component so different components don’t incorrectly move the Camera multiple times.

Next, delete the Main Camera GameObject from the XR Rig instance, and parent your existing Main Camera GameObject to the Camera Offset GameObject.

Make sure that the position and rotation of your Main Camera GameObject are both 0,0,0. Instead of changing the camera’s position, always change the position of the XR Rig GameObject. Also, make sure that any links from GameObjects or components to your Main Camera are still correct.

5. Configure your Project for XR

See the Configuring your Unity Project for XR section above.

6. Press Play

Now that your Scene has been successfully migrated, press Play and make sure that the camera’s starting location is the same as it was before migrating to the XR Plugin Framework. If it’s not, see the Troubleshooting section below.

Migrating a complex Scene

If your current Scene is using the implicit camera tracking from the legacy VR system, and the Main Camera is part of the GameObject hierarchy, follow these steps to migrate your legacy VR tracking system to the XR Plugin Framework.

The Implicit camera update would update the local transform of the Main Camera GameObject twice each frame, which made the Main Camera GameObject move relative to the position, scale and rotation of the hierarchy that it existed under.

In this scenario, you have two options to migrate your Scene:

1. Leave the existing hierarchy in place and add components to enable tracking in the current hierarchy
2. Migrate the existing hierarchy to use the XR Rig structure.

It’s generally recommended to leave the existing hierarchy in place if your Scene has functionality that relies on this hierarchy structure. If you have a relatively simple configuration, you can migrate directly to the XR Rig.

Leave in place

This method involves the least amount of modifications to the existing Scene hierarchy to enable tracking within Unity. It involves adding a Tracked Pose Driver to the Main Camera in your Scene. This ensures that any other functionality that requires your current GameObject hierarchy continues to function as before.

1. Locate your Main Camera and add a Tracked Pose Driver to it

Locate the Main Camera in the Scene.

Add a Tracked Pose Driver, using the same settings that the XR Rig’s Main Camera uses. The screenshot below shows these settings:

Do this for all the Main Cameras in your Scene. If you need to track other devices within your Scene, see the Tracked Pose Driver settings for the correct options for your use case.

2. Configure your Project for XR

See the Configuring your Unity Project for XR section above.

3. Press Play

Now that your Scene has been successfully migrated, press Play and make sure that the Camera’s starting location is the same as it was before migrating to the XR Plugin Framework. If it’s not, see the Troubleshooting section below.

Migrate to XR Rig

Because there are an infinite number of possible hierarchies in use, Unity can’t provide specific steps to migrate your current Scene hierarchy to use the XR Rig. See the XR Rig explanation section of the Legacy Input Helpers package documentation to understand what the XR Rig is intended to represent. This will allow you to map your existing hierarchy to the concepts within the XR Rig.

To configure your scene to use XR Management, see the Configuring your Unity Project for XR section above.

If there are still issues, see the Troubleshooting section below.

Troubleshooting

Issue	Possible causes
Camera is too high in the Scene	Is the Camera Offset component’s Requested Tracking Mode set correctly? Is the Camera Y Offset set too high?