Porting guides

Windows 10 includes support for immersive and holographic headsets directly. If you have built content for another device such as the Oculus Rift or HTC Vive, these have dependencies on libraries that exist above the operating system's platform API. Bringing existing content over to Windows Mixed Reality involves retargeting usage of these other SDKs to the Windows APIs. The Windows platform APIs for mixed reality only work in the Universal Windows Platform (UWP) app model. So if your app is not already built for UWP, porting to UWP will be part of the porting experience.

Porting overview

At a high-level, these are the steps involved in porting existing content:

  1. Upgrade to the latest Windows 10 insider flights. Work for the mixed reality developer experience on Desktop PCs is still underway. For active developers, we do not recommend using the Creators Update, instead jumping to the Windows Insider Fast updates, which have the latest platform fixes.
  2. Upgrade to the latest version of your graphics or game engine. Game engines will need to support the Windows 10 SDK version 10.0.15063.0 (released in April 2017) or higher.
  3. Upgrade any middleware, plug-ins or components. If your app contains any components, it's a good idea to upgrade to the latest version. Newer versions of most common plug-ins have support for UWP.
  4. Remove dependencies on duplicate SDKs. Depending on which device your content was targeting, you'll need to remove or conditionally compile out that SDK (e.g. SteamVR) so you can target the Windows APIs instead.
  5. Work through build issues. At this point, the porting exercise is specific to your app, your engine, and the component dependencies you have.

Common porting steps

Common step 1: Make sure you have the right development hardware

The install the tools page lists the recommended development hardware.

Common step 2: Upgrade to the latest flight of Windows 10

The Windows Mixed Reality platform is still under active development, and to be most effective, we recommend being on the "Windows Insider Fast" flight. In order to have access to windows flights, you will need to join the Windows Insider Program.

  1. Install the Windows 10 Creators Update
  2. Join the Windows Insider Program.
  3. Enable Developer Mode
  4. Switch to the Windows Insider Fast flights through Settings --> Update & Security Section

Common step 3: Upgrade to the most recent build of Visual Studio

Common step 4: Be Ready for The Store

Unity porting guidance

Unity step 1: Follow the common porting steps

Follow all of the common steps. When in step #3, select the Game Development with Unity workload. You may deselect the Unity Editor optional component since you'll be installing a newer version of Unity from the instructions below.

Unity step 2: Upgrade to the latest public build of Unity

  1. Download the latest public build of 5.6. At the time of this authoring, that is available here.
  2. Save a copy of your project before you get started
  3. Open your project, and let the automatic converter run on it
  4. Check and see if there are additional changes that you need to make to get your project running, and work through any remaining errors and warnings. Note: If you have middleware that you depend on, you may need to update that middleware to get going (more details in step 3 below).

Unity step 3: Upgrade your middleware to the latest versions

With the update to 5.6, there is a good chance that you need to update one or more middleware packages that your game or application depends on. Additionally, being on the latest version of all of your middleware will increase your likelihood of success throughout the rest of the porting process. Many middleware packages have recently added support for Universal Windows Platform (UWP), and upgrading to the most recent versions will let you leverage that work.

Unity step 4: Target your application to run on Universal Windows Platform (UWP)

After installing the tools, you need to get your app running as a Universal Windows app.

Note: If your application has any dependencies on device specific services, such as match making from Steam, you will need to disable them at this step. At a later time, you can hook up to the equivalent services that Windows provides.

Unity step 5: Download the Mixed Reality Technical Preview or 2017.2 beta build of Unity

  1. Please see the Install the tools page under the Unity Mixed Reality Technical Preview section, or the Unity 2017.2 beta section.
  2. Open your project and work through any errors and warnings. Please note that Unity MRTP 9 improved IL2CPP support; IL2CPP makes some UWP ports significantly easier.

Unity step 6: Get your Windows Mixed Reality hardware set up

  1. Review steps in Immersive headset setup
  2. Learn about Using the Windows Mixed Reality simulator and Navigating the Windows Mixed Reality home

Unity step 7: Target your application to run on Windows Mixed Reality

  1. First, you must remove or conditionally compile out any other library support specific to a particular VR SDK. Those assets frequently change settings and properties on your project in ways that are incompatible with other VR SDKs, such as Windows Mixed Reality.
    • For example, if your project references the SteamVR SDK, you will need to update your project to exclude those prefabs and script API calls when exporting for the Windows Store build target.
    • Specific steps for conditionally excluding other VR SDKs is coming soon.
  2. In your Unity project, target the Windows 10 SDK
  3. For each scene, setup the camera

Unity step 8: Use the stage to place content on the floor

You can build Mixed Reality experiences across a wide range of experience scales.

If you're porting a seated-scale experience, you're good to go! The world origin in Unity will be at the user's initial head position, facing forward (-Z). To recenter the user's seated origin, you can call Unity's VR.InputTracking.Recenter method.

If you're porting a standing-scale experience or room-scale experience, you'll need to place content relative to the floor. You reason about the user's floor using the spatial stage, which represents the user's defined floor-level origin and optional room boundary, set up during first run:

  1. To anchor a branch of your Unity hierarchy to the user's defined floor origin, add the StageRoot component to a root game object. The position and orientation of this object will be adjusted each frame to remain precisely in place at the user-defined location on the floor where the user intends to start Mixed Reality experiences, facing their defined forward direction (-Z). Child objects placed at Y=0 will then appear to be on the floor.
  2. In script code, you can then call the TryGetBounds methods on your StageRoot to get a boundary polygon. If the user defined a boundary, you can build a room-scale experience. You can test the placement of your content against this boundary polygon to ensure the user can physically reach those objects. Note that the system will automatically render the boundary when the user approaches it. Your app does not need to render the boundary itself.

Unity step 9: Work through your input model

Each game or application targeting an existing HMD will have a set of inputs that it handles, types of inputs that it needs for the experience, and specific APIs that it calls to get those inputs. We have invested in trying to make it as simple and straightforward as possible to take advantage of the inputs available in Windows Mixed Reality.

  1. Read through the Input porting guide for Unity for details of how Windows Mixed Reality exposes input, and how that maps to what your application may do today.
  2. Choose whether you are going to leverage Unity's cross-VR-SDK input API, or the MR-specific input API. The general Input.GetButton/Input.GetAxis APIs are used by Unity VR apps today for Oculus input and OpenVR input. If your apps are already using these APIs for motion controllers, this is the easiest path - you should just need to remap buttons and axes in the Input Manager.
    • You can access motion controller data in Unity using either the general cross-VR-SDK Input.GetButton/Input.GetAxis APIs or the MR-specific UnityEngine.XR.WSA.Input APIs. (previously in the UnityEngine.VR.WSA.Input namespace in Unity 5.6)
    • See the example in Toolkit that combines gamepad and motion controllers.

Unity step 10: Performance testing and tuning

Windows Mixed Reality will be available on a broad class of devices, ranging from high end gaming PCs, down to broad market mainstream PCs. Depending on what market you are targeting, there is a significant difference in the available compute and graphics budgets for your application. During this porting exercise, you are likely leveraging a premium PC, and have had significant compute and graphics budgets available to your app. If you wish to make your app available to a broader audience, you should test and profile your app on the representative hardware that you wish to target.

Both Unity and Visual Studio include performance profilers.

See also