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.

Prerequisites

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

Note

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

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.

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.

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:

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 ARM64
  4. Set Target device to HoloLens
  5. Set Build Type to D3D Project
  6. Set Target SDK Version 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 (should already be installed if you installed the Mixed Reality OpenXR plugin using MRFT)
  3. Check the Initialize XR on Startup box
  4. If targeting Desktop VR, stay on the PC Standalone tab (the monitor) and check the OpenXR and Windows Mixed Reality feature set boxes
  5. If targeting HoloLens 2, switch to the Universal Windows Platform tab (the Windows logo) and select the OpenXR and Microsoft HoloLens feature set boxes

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

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

Optimization

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.

Screenshot of the mixed reality menu item open with OpenXR selected

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.