To configure your Unity Project for XR, follow these steps:
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.
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:
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.
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.
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:
To migrate a simple Scene, follow the steps below.
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.
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.
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:
|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:
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.
See the Configuring your Unity Project for XR section above.
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.
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:
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.
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.
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.
See the Configuring your Unity Project for XR section above.
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.
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.
|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?