2. Initializing your project and deploying your first application

Overview

In this tutorial, you'll learn how to create a new Unity project, configure it for Mixed Reality Toolkit (MRTK) development, and import MRTK. You'll also walk through configuring, building, and deploying the basic Unity sample scene from Visual Studio to your HoloLens 2 or emulator.

Objectives

  • Learn how to configure Unity for HoloLens development
  • Learn how to build and deploy your app to HoloLens
  • Experience the spatial mapping mesh, hand meshes, and the framerate counter

Creating the Unity project

Launch Unity Hub, select the Projects tab, and click the down arrow next to the New button:

mr-learning-base

In the dropdown, select the Unity version specified in the Prerequisites:

mr-learning-base

Tip

If the particular Unity version is not available in Unity Hub, you can initiate the installation from Unity's Download Archive.

In the Create a new project window:

  • Ensure Templates is set to 3D
  • Enter a suitable Project Name, for example, MRTK Tutorials
  • Choose a suitable Location to store your project, for example, D:\MixedRealityLearning
  • Click the Create button to create and launch your new Unity project

mr-learning-base

Caution

When working on Windows, there is a MAX_PATH limit of 255 characters. Consequently, you should save the Unity project close to the root of the drive.

Wait for Unity to create the project:

mr-learning-base

Switching the build platform

In the Unity menu, select File > Build Settings... to open the Build Settings window:

mr-learning-base

In the Build Settings window, select Universal Windows Platform and click the Switch Platform button:

mr-learning-base

Wait for Unity to finish switching the platform:

mr-learning-base

When Unity has finished switching the platform, click the red x icon to close the Build Settings window:

mr-learning-base

Importing the TextMeshPro Essential Resources

In the Unity menu, select Window > TextMeshPro > Import TMP Essential Resources to open the Import Unity Package window:

mr-learning-base

In the Import Unity Package window, click the All button to ensure all the assets are selected, then click the Import button to import the assets:

mr-learning-base

Tip

The TextMeshPro Essential Resources are required by MRTK's UI elements. You can skip this step if you are not planning to use MRTK's UI elements in your project.

Importing the Mixed Reality Toolkit

Download the Unity custom package:

In the Unity menu, select Assets > Import Package > Custom Package... to open the Import package... window:

mr-learning-base

In the Import package... window, select the Microsoft.MixedReality.Toolkit.Unity.Foundation.2.4.0.unitypackage you downloaded and click the Open button:

mr-learning-base

In the Import Unity Package window, click the All button to ensure all the assets are selected, then click the Import button to import the assets:

mr-learning-base

Configuring the Unity project

1. Apply the MRTK Project Configurator settings

After Unity has finished importing the package from the previous section, the MRTK Project Configurator window should appear. If it doesn't, open the Configurator window by going to the Unity menu and selecting Mixed Reality Toolkit > Utilities > Configure Unity Project:

mr-learning-base

In the MRTK Project Configurator window, expand the Modify Configurations section, ensure all options are checked, and click the Apply button to apply the settings:

mr-learning-base

2. Configure additional project settings

In the Unity menu, select Edit > Project Settings... to open the Project Settings window:

mr-learning-base

In the Project Settings window, select Player > XR Settings, click the + icon, and select Windows Mixed Reality to add the Windows Mixed Reality SDK:

mr-learning-base

After Unity has finished importing the Windows Mixed Reality SDK, the MRTK Project Configurator window should appear again. If it doesn't, use the Unity menu to open it.

In the MRTK Project Configurator window, use the Audio spatializer dropdown to select the MS HRTF Spatializer, then click the Apply button to apply the setting:

mr-learning-base

In the Project Settings window, select Player > XR Settings, then use the Depth Format dropdown to select 16-bit depth:

mr-learning-base

In the Project Settings window, select Player > Publishing Settings, then in the Package name field, enter a suitable name, for example, MRTKTutorials-GettingStarted:

mr-learning-base

Note

The 'Package name' is the unique identifier for the app. You should change this identifier before deploying the app to avoid overwriting previously installed apps.

Tip

The 'Product Name' is the name displayed in the HoloLens Start menu. To make the app easier to locate during development, add an underscore in front of the name to sort it to the top.

Creating and configuring the scene

In the Unity menu, select File > New Scene to create a new scene:

mr-learning-base

In the Unity menu, select Mixed Reality Toolkit > Add to Scene and Configure... to add the MRTK to your current scene:

mr-learning-base

With the MixedRealityToolkit object still selected in the Hierarchy window, in the Inspector window, verify that the MixedRealityToolkit configuration profile is set to DefaultMixedRealityToolkitConfigurationProfile:

mr-learning-base

Important

Typically, you will use the DefaultHoloLens2ConfigurationProfile when developing for HoloLens. However, for this tutorial, you will use the DefaultMixedRealityToolkitConfigurationProfile, then in the next tutorial, Configuring the MRTK profiles, you will change to the DefaultHoloLens2ConfigurationProfile.

In the Unity menu, select File > Save As... to open the Save Scene window:

mr-learning-base

In the Save Scene window, navigate to your project's Scenes folder, give your scene a suitable name, for example, GettingStarted, and click the Save button to save the scene:

mr-learning-base

Building your application to your HoloLens 2

1. Build the Unity project

In the Unity menu, select File > Build Settings... to open the Build Settings window.

In the Build Settings window, click the Add Open Scenes button to add your current scene to the Scenes In Build list, then click the Build button to open the Build Universal Windows Platform window:

mr-learning-base

In the Build Universal Windows Platform window, choose a suitable location to store your build, for example, D:\MixedRealityLearning\Builds, create a new folder and give it a suitable name, for example, GettingStarted, and then click the Select Folder button to start the build process:

mr-learning-base

Wait for Unity to finish the build process:

mr-learning-base

2. Build and deploy the application

When the build process has completed, Unity will prompt Windows File Explorer to open the location you stored the build. Navigate inside the folder, and double-click the solution file to open it in Visual Studio:

mr-learning-base

Note

If Visual Studio asks you to install new components, take a moment to check that you have all the prerequisite components in the Install the Tools documentation.

Configure Visual Studio for HoloLens by selecting the Master or Release configuration, the ARM64 architecture, and Device as target:

mr-learning-base

Tip

If you're deploying to HoloLens (1st generation), select the x86 architecture.

Note

For HoloLens, you will typically build for the ARM architecture. However, there is a known issue in Unity 2019.3 that causes errors when selecting ARM as the build architecture in Visual Studio. The recommended workaround is to build for ARM64. If that is not an option, go to Edit > Project Settings > Player > Other Settings and disable Graphics Jobs.

Note

If you don't see Device as a target option, you may need to change the startup project for the Visual Studio solution from the IL2CPP project to the UWP project. To do this, in the Solution Explorer, right-click on YourProjectName (Universal Windows) and select Set as StartUp Project.

Connect your HoloLens to your computer, then select Debug > Start Without Debugging to build and deploy to your device:

mr-learning-base

Important

Before building to your device, the device must be in Developer Mode and paired with your development computer. Both of these steps can be completed by following these instructions.

Tip

You can also deploy to the HoloLens Emulator or create an App Package for sideloading.

Using Start Without Debugging automatically starts the app on your device without the Visual Studio debugger attached.

Select Build > Deploy Solution to deploy to your device without having the app start automatically.

Note

You may notice the Diagnostics profiler in the app, which you can toggle on or off by using the speech command Toggle Diagnostics. It's recommended that you keep the profiler visible most of the time during development to understand when changes to the app may impact performance. For example, HoloLens apps should continuously run at 60 FPS.

Congratulations

You've now deployed your first HoloLens app. As you walk around, you should see a spatial mapping mesh covering the surfaces that are perceived by the HoloLens. Additionally, you should see indicators on your hands and fingers for hand tracking and a frame rate counter for keeping an eye on app performance. These features are just a few foundational pieces included with MRTK. In the upcoming tutorials, you'll add content to your scene to explore the capabilities of HoloLens and the MRTK.

Next Tutorial: 3. Configuring the MRTK profiles