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.

Prerequisites

Minimum versions

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)

Note

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.

Note

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:

Mixed Reality Feature Tool packages window with open xr plugin highlighted

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:

Screenshot of Build Settings window open in the unity editor with PC, Mac & Standalone platform highlighted

If you're targeting HoloLens 2, you need to switch to the Universal Windows Platform:

  1. Select File > Build Settings...
  2. Select Universal Windows Platform in the Platform list and select Switch Platform
  3. Set Architecture to ARM 64
  4. Set Target device to HoloLens
  5. Set Build Type to D3D
  6. Set UWP SDK to Latest installed

Screenshot of Build Settings window open in unity editor with Universal Windows Platform highlighted

Configuring XR Plugin Management for OpenXR

To set OpenXR as the the runtime in Unity:

  1. In the Unity Editor, navigate to Edit > Project Settings
  2. In the list of Settings, select XR Plugin Management
  3. Check the Initialize XR on Startup and OpenXR boxes
  4. If targeting HoloLens 2, make sure you're on the UWP platform and select Microsoft HoloLens Feature Set

Screenshot of the project settings panel open in the Unity editor with XR Plug-in management highlighted

Optimization

If you're developing for HoloLens 2, navigate to Mixed Reality> OpenXR > Apply recommended project settings for HoloLens 2 to get better app performance.

Screenshot of the mixed reality menu item open with OpenXR selected

Important

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.

Screenshot of the OpenXR project validation window

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.