Unity 2020.3 LTS also supports a public preview of the Mixed Reality OpenXR plugin. The Mixed Reality OpenXR plugin fully supports AR Foundation 4.0, providing ARPlaneManager and ARRaycastManager implementations. This enables you to write hit-testing code once that then spans HoloLens 2 and ARCore/ARKit phones and tablets. The Mixed Reality OpenXR Plugin package is an extension of Unity's OpenXR Plugin and supports a suite of features for HoloLens 2 and Windows Mixed Reality headsets. Before continuing, make sure your Unity project is configured for OpenXR.

• Unity Openxr Resolving Packages
• Xr Plugin Unity
• Unity Openxr Support
• Unity Openxr Oculus

Getting your holograms to stay in place, move with you, or in some cases position themselves relative to other holograms is a big part of creating Mixed Reality applications. This article will take you through our recommended solution using World Locking Tools, but we'll also cover manually setting up spatial anchors in your Unity projects. Before we jump into any code, it's important to understand how Unity handles coordinate space and anchors in its own engine.

World-scale coordinate systems

Today, when writing games, data visualization apps, or virtual reality apps, the typical approach is to establish one absolute world coordinate system that all other coordinates can reliably map back to. In that environment, you can always find a stable transform that defines a relationship between any two objects in that world. If you didn't move those objects, their relative transforms would always remain the same. This kind of global coordinate system is easy to get right when rendering a purely virtual world where you know all of the geometry in advance. Room-scale VR apps today typically establish this kind of absolute room-scale coordinate system with its origin on the floor.

In contrast, an untethered mixed reality device such as HoloLens has a dynamic sensor-driven understanding of the world, continuously adjusting its knowledge over time of the user's surroundings as they walk many meters across an entire floor of a building. In a world-scale experience, if you placed all your holograms in a naive rigid coordinate system, those holograms would end up drifting over time, either based on the world or relative to each other.

For example, the headset may currently believe two locations in the world to be 4 meters apart, and then later refine that understanding, learning that the locations are in fact 3.9 meters apart. If those holograms had initially been placed 4 meters apart in a single rigid coordinate system, one of them would then always appear 0.1 meters off from the real world.

You can manually place spatial anchors in Unity to maintain a hologram's position in the physical world when the user is mobile - however, this sacrifices the self-consistency within the virtual world. Different anchors are constantly moving in relation to one another, and are also moving through the global coordinate space. In this scenario, simple tasks like layout become difficult and physics simulation problematic.

World Locking Tools gets you the best of both worlds, stabilizing a single rigid coordinate system using an internal supply of spatial anchors spread throughout the virtual scene as the user moves around. The tools analyze the coordinates of the camera and those spatial anchors every frame. Instead of changing the coordinates of everything in the world to compensate for the corrections in the coordinates of the user's head, the tools just fix the head's coordinates instead.

Choosing your world locking approach

• Our recommendation is to use World Locking Tools for all your hologram positioning needs.
  • World Locking Tools provides a stable coordinate system that minimizes the visible inconsistencies between virtual and real world markers. Put another way, it world-locks the entire scene with a shared pool of anchors, rather than locking each group of objects with the group's own individual anchor.
• For Unity 2019/2020 using OpenXR or the Windows XR Plugin, you need to use ARAnchorManager
• For older Unity versions or WSA projects, you need to use WorldAnchor

Setting up world locking

We recommend installing World Locking Tools using the new Mixed Reality Feature Tool. Once you've downloaded the Mixed Reality Feature Tool from the link below, select the latest version of WLT Core from the World Locking Tools section:

Automated setup

When your project is ready to go, run the configure scene utility from Mixed Reality Toolkit > Utilities > World Locking Tools:

Important

The Configure scene utility can be rerun at any time. For example, it should be rerun if the AR target has been changed from Legacy to XR SDK. If the scene is already properly configured, running the utility has no effect.

Visualizers

During early development, adding visualizers can be helpful to ensure WLT is setup and working properly. They can be removed for production performance, or if for any reason are no longer needed, using the Remove visualizers utility. More details on the visualizers can be found in the Tools documentation.

The Mixed Reality OpenXR Plugin supplies basic anchor functionality through an implementation of Unity’s ARFoundation ARAnchorManager. To learn the basics on ARAnchors in ARFoundation, visit the ARFoundation Manual for AR Anchor Manager.

Building a world-scale experience

Namespace:UnityEngine.XR.WSA
Type:WorldAnchor

For true world-scale experiences on HoloLens that let users wander beyond 5 meters, you'll need new techniques beyond those used for room-scale experiences. One key technique you'll use is to create a spatial anchor to lock a cluster of holograms precisely in place in the physical world, no matter how far the user has roamed, and then find those holograms again in later sessions.

In Unity, you create a spatial anchor by adding the WorldAnchor Unity component to a GameObject.

Adding a World Anchor

To add a world anchor, call AddComponent<WorldAnchor>() on the game object with the transform you want to anchor in the real world.

That's it! This game object will now be anchored to its current location in the physical world - you may see its Unity world coordinates adjust slightly over time to ensure that physical alignment. Refer to loading a world anchor to find this anchored location again in a future app session.

Removing a World Anchor

If you no longer want the GameObject locked to a physical world location and don't intend on moving it this frame, then you can just call Destroy on the World Anchor component.

If you want to move the GameObject this frame, you need to call DestroyImmediate instead.

Moving a World Anchored GameObject

GameObject's cannot be moved while a World Anchor is on it. If you need to move the GameObject this frame, you need to:

1. DestroyImmediate the World Anchor component
2. Move the GameObject
3. Add a new World Anchor component to the GameObject.

Handling Locatability Changes

A WorldAnchor may not be locatable in the physical world at a point in time. If that occurs, Unity won't be updating the transform of the anchored object. This also can change while an app is running. Failure to handle the change in locatability will cause the object to not appear in the correct physical location in the world.

To be notified about locatability changes:

1. Subscribe to the OnTrackingChanged event
2. Handle the event

The OnTrackingChanged event will be called whenever the underlying spatial anchor changes between a state of being locatable vs. not being locatable.

Then handle the event:

Sometimes anchors are located immediately. In this case, this isLocated property of the anchor will be set to true when AddComponent() returns. As a result, the OnTrackingChanged event won't be triggered. A clean pattern would be to call your OnTrackingChanged handler with the initial IsLocated state after attaching an anchor.

Persistent world locking

Spatial anchors save holograms in real-world space between application sessions. Once saved in the HoloLens' anchor store, they can be found and loaded in different sessions and are an ideal fallback when there's no internet connectivity.

Unity Openxr Resolving Packages

Important

Local anchors are stored on device, while Azure Spatial Anchors are stored in the cloud. If you're looking to use Azure cloud services to store your anchors, we have a document that can walk you through integrating Azure Spatial Anchors. Note that you can have local and Azure anchors in the same project without conflict.

By default, World Locking Tools will restore Unity's coordinate system relative to the physical world across sessions. This means that to have a hologram appear the same place in the physical world after quitting and re-running the application, the hologram only needs to have the same Pose again.

If the application needs finer control, Auto-Save and Auto-Load may be disabled in the inspector, and persistence managed from a script as described in the persistence section of the documentation.

An additional API called the XRAnchorStore enables anchors to be persisted between sessions. The XRAnchorStore is a representation of the saved anchors on a device. Anchors can be persisted from ARAnchors in the Unity scene, loaded from storage into new ARAnchors, or deleted from storage.

Note

These anchors are to be saved and loaded on the same device. Cross-device anchor storage will be supported through Azure Spatial Anchors in a future release.

Namespaces

For Unity 2020 and OpenXR:

or Unity 2019/2020 + Windows XR Plugin:

Public methods

Getting an anchor store reference

To load the XRAnchorStore with Unity 2020 and OpenXR, use extension method on the XRAnchorSubsystem, the subsystem of an ARAnchorManager:

To load the XRAnchorStore with Unity 2019/2020 and the Windows XR Plugin, use the extension method on the XRReferencePointSubsystem (Unity 2019) or XRAnchorSubsystem (Unity 2020), the subsystem of an ARReferencePointManager/ARAnchorManager:

Loading an anchor store

To load an anchor store in Unity 2020 and OpenXR, access it from an ARAnchorManager's subsystem as follows:

or with Unity 2019/2020 and the Windows XR Plugin:

To see a full example of persisting / unpersisting anchors, check out the Anchors -> Anchors Sample GameObject and AnchorsSample.cs script in the Mixed Reality OpenXR Plugin Sample Scene:

The WorldAnchorStore is the key to creating holographic experiences where holograms stay in specific real world positions across instances of the application. Users can then pin individual holograms wherever they want, and find them later in the same spot over many uses of your app.

Namespace:UnityEngine.XR.WSA.Persistence
Class:WorldAnchorStore

The WorldAnchorStore will allow you to persist the location of WorldAnchor's across sessions. To actually persist holograms across sessions, you'll need to separately keep track of your GameObjects that use a particular world anchor. It often makes sense to create a GameObject root with a world anchor and have children holograms anchored by it with a local position offset.

To load holograms from previous sessions:

1. Get the WorldAnchorStore
2. Load app data relating to the world anchor, which gives you the ID of the world anchor
3. Load a world anchor from its ID

To save holograms for future sessions:

1. Get the WorldAnchorStore
2. Save a world anchor specifying an ID
3. Save app data relating to the world anchor along with an ID

Getting the WorldAnchorStore

You'll want to keep a reference to the WorldAnchorStore so you know when it's ready to perform an operation. Since this is an async call, potentially as soon as start up, you want to call:

StoreLoaded in this case is our handler for when the WorldAnchorStore has completed loading:

We now have a reference to the WorldAnchorStore, which we'll use to save and load specific World Anchors.

Saving a WorldAnchor

To save, we simply need to name what we are saving and pass it in the WorldAnchor we got before when we want to save. Note: trying to save two anchors to the same string will fail (store.Save will return false). Delete the previous save before saving the new one:

Loading a WorldAnchor

And to load:

We additionally can use store.Delete() to remove an anchor we previously saved and store.Clear() to remove all previously saved data.

Enumerating Existing Anchors

To discover previously stored anchors, call GetAllIds.

Persisting holograms for multiple devices

You can use Azure Spatial Anchors to create a durable cloud anchor from a local WorldAnchor, which your app can then locate across multiple HoloLens, iOS and Android devices, even if those devices aren't present together at the same time. Because cloud anchors are persistent, multiple devices over time can each see content rendered relative to that anchor in the same physical location.

To get started building shared experiences in Unity, try out the 5-minute Azure Spatial Anchors Unity quickstarts.

Once you're up and running with Azure Spatial Anchors, you can then create and locate anchors in Unity.

Sharing coordinate spaces

If you want to share a world locked coordinate space, check out our comprehensive shared experience documentation.

Note that Azure Spatial Anchors is not yet supported directly within World Locking Tools, and so shared experiences will require you to manually create spatial anchors.

Next Development Checkpoint

If you're following the Unity development checkpoint journey we've laid out, you're in the midst of exploring the Mixed Reality core building blocks. From here, you can continue to the next building block:

Or jump to Mixed Reality platform capabilities and APIs:

You can always go back to the Unity development checkpoints at any time.

See Also

Caution

See this page on the new docs website.We've moved so we can provide you with a better docs experience. We will no longer be maintaing documentation on Github.Check out the new site to get started with MRTK in Unity!

XR SDK is Unity's new XR pipeline in Unity 2019.3 and beyond. In Unity 2019, it provides an alternative to the existing XR pipeline. In Unity 2020, it will become the only XR pipeline in Unity.

Prerequisites

To get started with the Mixed Reality Toolkit, follow the provided steps to add MRTK to a project.

Add XR SDK to a Unity project

Windows Mixed Reality, Oculus, and OpenXR are supported on XR SDK.

Required in Unity

OpenXR (Preview)

Important

OpenXR in Unity is only supported on Unity 2020.2 and higher.

Currently, it also only supports x64 and ARM64 builds.

1. Follow the Using the Mixed Reality OpenXR Plugin for Unity guide, including the steps for configuring XR Plugin Management and Optimization to install the OpenXR plug-in to your project.
2. Ensure that the following have successfully installed:
   1. XR Plugin Management
   2. OpenXR Plugin
   3. Mixed Reality OpenXR Plugin

Note

For the initial release of MRTK and OpenXR, only the HoloLens 2 articulated hands and Windows Mixed Reality motion controllers are natively supported. Support for additional hardware will be added in upcoming releases.

Windows Mixed Reality

1. Go into Unity's Package Manager and install the Windows XR Plugin package, which adds support for Windows Mixed Reality on XR SDK. This will pull down a few dependency packages as well. Ensure the following all successfully installed:
   1. XR Plugin Management
   2. Windows XR Plugin
   3. XR Legacy Input Helpers
2. Go to Edit > Project Settings.
3. Click on the XR Plug-in Management tab in the Project Settings window.
4. Go to the Universal Windows Platform settings and ensure Windows Mixed Reality is checked under Plug-in Providers.
5. Ensure that Initialize XR on Startup is checked.
6. (Required for in-editor HoloLens Remoting, otherwise optional) Go to the Standalone settings and ensure Windows Mixed Reality is checked under Plug-in Providers. Also ensure that Initialize XR on Startup is checked.
7. (Optional) Click on the Windows Mixed Reality tab under XR Plug-in Management and create a custom settings profile to change the defaults. If the list of settings are already there, no profile needs to be created.

Required in MRTK

If using OpenXR, choose 'DefaultOpenXRConfigurationProfile' as the active profile or clone it to make customizations.

If using other XR runtimes in the XR Plug-in Management configuration, like Windows Mixed Reality or Oculus, choose 'DefaultXRSDKConfigurationProfile' as the active profile or clone it to make customizations.

These profiles are set up with the correct systems and providers, where needed.

To migrate an existing profile to XR SDK, the following services and data providers should be updated:

Camera

From WindowsMixedReality.WindowsMixedRealityCameraSettings

Xr Plugin Unity

to

Input

From WindowsMixedReality.Input.WindowsMixedRealityDeviceManager

to

OpenXR:

Windows Mixed Reality:

Boundary

From MixedRealityBoundarySystem

to

Spatial awareness

From WindowsMixedReality.SpatialAwareness.WindowsMixedRealitySpatialMeshObserver

Unity Openxr Support

to

Controller mappings

Unity Openxr Oculus

If using custom controller mapping profiles, open one of them and run the Mixed Reality Toolkit -> Utilities -> Update -> Controller Mapping Profiles menu item to ensure the new XR SDK controller types are defined.

See also