Setting up your XR configuration
When you start a new Unity project, you have three different options for handling your XR needs:
- OpenXR plugin
- Windows XR plugin
- Legacy XR plugin
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, (we recommend 2020.3.8f1 or above)
The instructions in this page will set you up with the latest and greatest Unity and OpenXR requirements listed below:
- Latest Unity OpenXR plugin, (we recommend 1.2 or later)
- Latest Mixed Reality OpenXR Plugin, (we recommend version 1.0.0 or later)
- (Optional) Latest MRTK, (we recommend version 2.7 or later)
- (Optional) Latest Universal Render Pipeline package, (we recommend version 10.5.1 or later)
If you're building VR applications on Windows PC, the Mixed Reality OpenXR plugin is not necessarily required. However, you'll want to install the plugin if you're customizing controller mapping for HP Reverb G2 controllers or building apps that work on both HoloLens 2 and VR headsets.
Setting up your project with MRTK
MRTK for Unity provides a cross-platform input system, foundational components, and common building blocks for spatial interactions. MRTK version 2 intends to speed up application development for Microsoft HoloLens, Windows Mixed Reality immersive (VR) headsets, and OpenVR platform. The project is aimed at reducing barriers to entry, creating mixed reality applications, and contributing back to the community as we all grow.
Take a look at MRTK's documentation for more feature details.
Using MRTK with OpenXR support
MRTK-Unity 2.7 release provides better supports for the Mixed Reality OpenXR plugin.
Open the Mixed Reality Feature Tool again to install the Mixed Reality Toolkit, if you haven't already. OpenXR support is in the Foundation package.
See the MRTK documentation for more in-depth information on migrating 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.
Manual setup without MRTK
While Microsoft and the community have created opensource tools such as the Mixed Reality Toolkit (MRTK) that will automatically set up the WMR environment, many developers 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 Mixed Reality Toolkit 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 ARM 64
- Set Target device to HoloLens
- Set Build Type to D3D
- Set UWP SDK 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
- Check the Initialize XR on Startup and OpenXR boxes
- If targeting HoloLens 2, make sure you're on the UWP platform and select Microsoft HoloLens Feature Set
If you're developing for HoloLens 2, navigate to Mixed Reality> OpenXR > Apply recommended project settings for HoloLens 2 to get better app performance.
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.
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.