Setting up your XR configuration
Once you've chosen a Unity version, the next step is to select the XR configuration you'll use to build your mixed reality app:
Choosing an XR configuration
When you start a new Unity project, you have various XR configurations you can select from: the Mixed Reality OpenXR plugin, the Windows XR plugin and Legacy Built-in XR.
The Mixed Reality OpenXR plugin is Microsoft's recommendation for Unity 2020 LTS or later. As new features are developed in the future, they will only be included in the Mixed Reality OpenXR plugin going forward.
The Mixed Reality OpenXR plugin fully supports AR Foundation 4.0, providing ARPlaneManager and ARRaycastManager implementations. This enables you to write raycasting code once that then spans HoloLens 2 and ARCore/ARKit phones and tablets.
- Latest tools for HoloLens 2 development
- Latest Unity 2020.3 LTS: version 2020.3.8f1 or later
Recommended package versions
The instructions in this page will set you up with the core Unity OpenXR packages required to deploy HoloLens 2 or Windows Mixed Reality apps:
- Unity OpenXR plugin: version 1.2 or later
- Mixed Reality OpenXR plugin: version 1.0.0 or later
If you use the following packages in your project, you will need to ensure that you use at least the minimum versions listed below:
- MRTK: version 2.7.2 or later
- AR Foundation: version 4.1.1 or later
- Universal Render Pipeline (URP): version 10.5.1 or later
- Azure Spatial Anchors: version 2.10 or later
- Azure Remote Rendering: version 1.0.15 or later
If you're building VR applications on Windows PC, the Mixed Reality OpenXR plugin is not strictly required. However, you'll want to install the plugin if you're setting up input bindings for HP Reverb G2 controllers or building apps that work on both HoloLens 2 and VR headsets.
Setting up your project with MRTK
The easiest way to get your Unity project set up for mixed reality is with the Mixed Reality Toolkit (MRTK). MRTK for Unity is an open-source, cross-platform development kit designed to make it easy to build amazing mixed reality applications.
MRTK provides a cross-platform input system, foundational components, and common building blocks for spatial interactions. With MRTK version 2, you can speed up your application development for Microsoft HoloLens, Windows Mixed Reality immersive (VR) headsets, and many other VR/AR devices. The project is aimed at reducing barriers to entry, enabling everyone to build mixed reality applications and contribute back to the community as we all grow.
To get started with a new Unity project using MRTK, start from step 2 in the MRTK tutorial:
If you're upgrading an existing MRTK project to OpenXR, you'll first want to upgrade MRTK-Unity to the latest version (version 2.7.2 or later) to get key fixes for compatibility with the Mixed Reality OpenXR plugin. Use the Mixed Reality Feature Tool to upgrade to the latest version of MRTK and then follow the manual OpenXR setup steps below. See the MRTK documentation for more in-depth information on migrating an existing MRTK project to OpenXR.
When upgrading from a previous version of MRTK older than 2.5.3, ensure the following line is in the Assets/MixedRealityToolkit.Generated/link.xml file:
<assembly fullname = "Microsoft.MixedReality.Toolkit.Providers.OpenXR" preserve="all"/>
This line will be added by default if you started with MRTK 2.5.4 or newer.
To learn more about the Mixed Reality Toolkit, check out the MRTK documentation.
Manual setup without MRTK
While Microsoft and the community have created open source tools such as the Mixed Reality Toolkit (MRTK) that will automatically set up your environment for mixed reality, some developers may wish to build their experiences from the ground up.
Install the OpenXR plugin with the new Mixed Reality Feature Tool application. Follow the installation and usage instructions and select the Mixed Reality OpenXR Plugin package in the Platform Support category:
Setting your build target
If you're targeting Desktop VR, we suggest using the PC Standalone Platform selected by default on a new Unity project:
If you're targeting HoloLens 2, you need to switch to the Universal Windows Platform:
- Select File > Build Settings...
- Select Universal Windows Platform in the Platform list and select Switch Platform
- Set Architecture to ARM64
- Set Target device to HoloLens
- Set Build Type to D3D Project
- Set Target SDK Version to Latest installed
Configuring XR Plugin Management for OpenXR
To set OpenXR as the the runtime in Unity:
- In the Unity Editor, navigate to Edit > Project Settings
- In the list of Settings, select XR Plugin Management (should already be installed if you installed the Mixed Reality OpenXR plugin using MRFT)
- Check the Initialize XR on Startup box
- If targeting Desktop VR, stay on the PC Standalone tab (the monitor) and check the OpenXR and Windows Mixed Reality feature set boxes
- If targeting HoloLens 2, switch to the Universal Windows Platform tab (the Windows logo) and select the OpenXR and Microsoft HoloLens feature set boxes
If you see a yellow warning icon next to OpenXR Plugin, click the icon and select Fix All before continuing. The Unity Editor may need to restart itself for the changes to take effect.
If you're developing for HoloLens 2, select the Mixed Reality > Project > Apply recommended project settings for HoloLens 2 menu item to get better app performance.
You're now ready to begin developing with OpenXR in Unity! Continue on to the next section to learn how to use the OpenXR samples.
Unity sample projects for OpenXR and HoloLens 2
Check out the OpenXR Mixed Reality samples repo for sample unity projects showcasing how to build Unity applications for HoloLens 2 or Mixed Reality headsets using the Mixed Reality OpenXR plugin.
Or, if you're ready to get started on your own from a blank project, proceed to the Camera setup article.