1.1 - VR Project Setup

1. Open a new VR project

The first thing you have to do is create a new Unity project configured for VR.

1. Download and extract the Create with VR starter project:

• Click to download the file: Create with VR Starter Project.

• To extract on Mac: double-click the downloaded file.

• To extract on Windows: right-click the downloaded file and select Extract All.

2. Rename and relocate the project on your computer:

• Locate the folder called “VR Room” inside the extracted folder.

• If you want, rename the project folder to “VR Room - [Your Name]”

• Move the project folder to a logical directory on your computer (e.g. a folder called “Create with VR” on your desktop).

3. Add the VR Room project to the Unity Hub:

• Open the Unity Hub.

• Add your VR Room Project to the list of projects in the Unity Hub.
  If you are not sure how to do this, check out this tutorial on adding projects to the Unity Hub.

• If you see a warning icon next to the Editor version of your project, don’t worry.

• This just means that the project was created with a specific version of Unity that you don’t have on your computer. As long as you have installed a version of Unity beginning with 2022.3, the project will run perfectly.

4. Open the project in Unity 2022.3 LTS (Long-Term Support):

• From the Editor Version dropdown, select a version of Unity beginning with 2022.3, then select Open with 2022.3.X.

• If a window pops up asking if you want to “Change Editor Version?”, select Change Version.

• If a warning pops up that you are Opening Project in a Non-Matching Editor Installation”, select Continue.

• Your project should now open in Unity.

• If there are yellow warning messages in the Console window about some of the assets, you can ignore them or clear them.

5. Explore the contents of the starter project and how it differs from a typical empty project:

• From the top menu, select Window > Package Manager.

• In the left panel of the Package Manager, locate the packages installed in this project (with checkmarks next to them), including:

• OpenXR Plugin

• Universal RP (Render Pipeline)

• XR Plugin Management

• XR Interaction Toolkit

• Note: to filter and view only packages currently installed in the project, from the top-left corner of the Package Manager window, select Packages: In Project.

You should now have your new VR starter project open to an empty scene and understand which packages allow for compatibility with VR.

Related Resources:

• Blog about the Unity XR Plugin Framework

2. Open and explore the starter scene

Before you run the project, you should choose a more interesting environment to experience in VR.

1. Rename and open the Starter Scene:

• From the Project window, open the Scenes folder.

• Rename the “Create-with-VR_Starter-Scene” as “[Your_Name] Room”.

• Double-click on your renamed scene to open it.

2. Explore the contents of this scene and how it differs from a typical empty Scene:

• From the Hierarchy, select the XR Rig object and inspect the XR Origin component.

• Select XR Rig > Camera Offset > Main Camera and inspect the Tracked Pose Driver component.

• Select either the LeftHand Controller or RightHand Controller object and inspect the XR Controller component.

• Select the Input Action Manager object and inspect the Input Action Manager component.

You should now have your new scene open. You should also have a broad understanding of the components of the scene that make it different from a typical Unity scene.

Note: This scene and its settings have been pre-configured in this starter project, since they are required for VR development in this course. If you want to learn how to configure a VR-ready project similar to this from scratch, there are instructions in this tutorial: Create a VR Starter Project from Scratch.

3. Add a room and background

This empty scene would be boring to explore in VR, so you should add a room that will be a bit more interesting and will provide more perspective when you’re in VR.

1. Add a room to the scene:

• In the Project window, expand Course Library > _Prefabs > Rooms.

• Drag one of the Room_[style] prefabs into the Hierarchy.

• From the Hierarchy, delete the Plane object.

2. Add an environment outside the room’s windows:

• Open the Course Library > _Prefabs > Environments folder

• Drag one Foreground object and one Background object into the Hierarchy.

3. Adjust the sunlight in the room:

• Change the X and Y rotation of the Directional Light object to change the way sunlight enters your room.

You should now have room, foreground, and background objects in your scene from the course library, with sunlight entering the room at the desired angle.

Note: Please be aware that some of the screen captures used in this course were taken in a previous version of the Unity Editor. As a result, you may notice slight differences in the layout of the current version. For instance, in Unity 2022.3, the View, Move, Rotate and Scale, Rect, and, Transform tools are located on a floating toolbar on the leftmost side of the Scene view.

New position of scene manipulation tools

4. Run the app with the Device Simulator

You can test the scene with a Device Simulator. This simulator allows you to test the app in-editor using the mouse and keyboard, rather than having to connect to a device and put it on. This can be helpful for quick tests.

1. Add the Device Simulator to the scene:

• From the Project window, open Samples > XR Interaction Toolkit > [version] > XR Device Simulator.

• Drag the XR Device Simulator Prefab into the Hierarchy.

• Click Play to test the simulator.

2. Experiment with the keyboard and mouse controls:

• Note: To use the simulator effectively, a mouse with a clickable scroll wheel is required.

• To control the camera: hold right-click.

• To control the left controller: hold Left Shift or toggle with T.

• To control the right controller: hold the Spacebar or toggle with Y.

• To pan around with a device: move the mouse.

• To rotate a device: hold the middle mouse button.

• To reset the position and rotation of devices: press V.

• If you’d like a helpful guide, download the PDF of the Rig Simulator Shortcut Cheat Sheet.

3. See more controls available for the device simulator:

• From the Hierarchy, select the XR Device Simulator.

• In the XR Device Simulator component, double-click on one of the Action variables to open the Action Editor.

• Expand the Actions to view their Bindings.

• From the left Action Maps panel, select either Main or Input Controls to view additional action mappings.

4. Important: disable the Device Simulator if you do not plan on using it:

• Select the Device Simulator object then disable it in the Inspector window.

• Having the device simulator active when running the project on your device will cause problems.

You should now be able to look around your room with your mouse and keyboard using the Device Simulator.

Note: Please be aware that the updated Device Simulator now contains a helpful floating panel that displays all the available keyboard options when running the simulation.

5. Test in VR through Unity

If you are using a Windows computer, follow this step to test on your device. Otherwise, skip this step.

If you are using a Mac for development, this step is not relevant. You will learn how to test your app in the next step when you build your app directly onto your device.

In order to run the project on your device through Unity, you need to install the correct plug-in for development. OpenXR is an open source API that connects Unity to supported VR hardware devices. It is recommended that you use this plug-in, since it allows you to deploy to multiple devices through a single, standardized API.

1. Install the OpenXR Plugin for desktop testing:

• From the top menu, select Edit > Project Settings, then select the XR Plug-in Management panel from the sidebar.

• In the Windows, Mac, Linux tab, select OpenXR from the list of available Plug-in Providers to install that plug-in.

2. Resolve any warnings by setting up an interaction profile.

• After adding the OpenXR plugin, there may be a warning or error icon that appears next to the plugin Name.
  If there are no warnings or errors, you can skip to step 3 below to connect your device through the Quest Link Software.

• If there is a warning, click on the warning icon to open the OpenXR Project Validation window, which will tell you that you need to add an interaction profile for the device you’re using.

• Select the Edit button to open the OpenXR settings panel.

• In the Windows, Mac, Linux tab, make sure the Oculus Touch Controller Profile appears in the list of Interaction Profiles, then enable all available OpenXR Feature Groups.

• If you are using a different device, such as the Valve Index or HTC Vive, add its interaction profile instead.

• There should no longer be any warnings in the XR Plugin Management panel. If there are, select them and follow the recommended steps to resolve them.

• If you are having trouble resolving warnings or errors, or if you need help troubleshooting, check out this detailed documentation on configuring the OpenXR plugin.

3. Connect your device through the Quest Link Software:

• Make sure your device is plugged into your computer using a compatible cable.

• Make sure the Quest App is running and has successfully recognized your device.

• If you have not yet downloaded the Quest App, you find it on the Link Setup page.

4. Test the project on your device:

• Make sure the XR Device Simulator in your scene is disabled. If it is enabled, your head tracking will not work.

• Select Play in the Unity Editor and put on your headset.

On a Windows computer, you should now be able to quickly test your app on your device through Unity.

6. Build and run on your device

If you are using a Quest, follow this step to build the app onto your device. Otherwise, skip this step.

Since the Quest is a standalone device (meaning it does not need to be connected to a computer), you can build an app and test it directly on the device, disconnected from your computer.

If you are on a Mac and cannot test your app through the Windows Quest software as in the previous step, this will be the primary way for you to test your app on your headset.

In order to build your app to the Quest headset, you will need to configure plug-ins for the Android build target.

1. Install the OpenXR for Android builds:

• From the top menu, select Edit > Project Settings, then select the XR Plug-in Management panel from the sidebar.

• From the XR Plug-in Management settings, select the Android tab, then select OpenXR from the list of available Plug-in Providers to install that plug-in.
  Note: You will only have an Android tab if you installed the Android export module.

• If you don’t see an option for OpenXR in the Android tab, first go back to the Desktop tab and select OpenXR there, then return to the Android tab.

2. Resolve warnings by setting up an interaction profile.

• Click on the new warning or error icon that appears to open the OpenXR Project Validation window,

• If there is an option to Fix All, select that to address some of the warnings.

• A warning will likely still remain telling you that you need to add an interaction profile. Select the Edit button to open the OpenXR settings panel.

• In the OpenXR settings, in the Android tab, select the + button to add the appropriate profile for your device.

• For models of the Quest, select the Oculus Touch Controller Profile, then enable the Meta Quest Support feature groups.

• If any additional errors or warnings appear, click on the error or warning icons to resolve them.

3. Prepare your scene for building:

• Make sure the XR Device Simulator in your scene is disabled. If it is enabled, your head tracking will not work.

• From the top menu, click File > Build Settings.

• Click Add Open Scenes to add your scene.

4. Switch to the Android build platform:

• In the Platform section, select Android.

• Click Switch Platform, and wait for your project to switch to the Android platform.

• Note: Android will only show up as a possible build target if you successfully installed the Android Export Module during installation of the Unity Editor.

5. Select your device as the build target:

• Make sure your VR device is turned on and plugged in.

• Next to the Run Device drop-down, click Refresh, then select your VR device. Your device may show up as a device ID or as a device name.

• Note: If your device does not show up in the list, try putting on the device. It may prompt you to Allow USB debugging. If it is still not showing up in the list, try restarting your device, making sure it’s in Developer Mode, or restarting Unity.

6. Build and run your project on your device:

• Click Build and Run.

• When prompted to choose a location, create a new “Builds” folder, then Save your project as “[YourName] - VR Room - 1.1”.

• Note: When you build your app for the first time, it may take several minutes to compile.

You should now be able to test the app on your device, untethered from your computer.

Note: The app is automatically saved onto your device in the “Unknown Sources” section of your App Library. You may need to follow steps to allow apps from unknown sources in order to locate your app.

Troubleshooting tips:

• If the app runs, but it does not take up the entire field of view, it is likely a problem with plug-ins.

• If the app runs, but the entire scene moves along with your head, it is likely because you have the Device Simulator active or you do not have the Input Action Manager configured properly.

7. Test on other OpenXR-compatible devices

If you are using a different OpenXR-compatible device, such as the Valve Index, HTC Vive, or a Windows Mixed Reality headset, follow this step to test on your device. Otherwise, skip this step.
In order to test the project on one of these devices, you need to install the OpenXR plugin and enable the feature set for your specific device.

1. Configure the OpenXR Plugin for your device:

• Follow the instructions on the OpenXR Manual page to install the OpenXR Plugin, enable it in XR Plugin Management, and configure it for your particular device.

2. Connect your device through the SteamVR app:

• Make sure your device is plugged into your computer using a compatible cable.

• Make sure the SteamVR app is running and has successfully recognized your device.

3. Test the project on your device:

• Make sure the Device Simulator in your scene is disabled. If it is enabled, your head tracking will not work.

• Select Play in the Unity Editor and put on your headset.

You should now be able to quickly test your app on your headset through SteamVR.

8. Recap

New Features:

• Project is set up

• Scene set up with Room

• Tested with Device Simulator

• Run on device

New Concepts & Skills:

• Pipelines for different types of hardware

• Packages required for VR Development

• VR scene vs typical Unity scene

• Rig Simulator vs on-Device testing

• Tethered vs Standalone testing

Next Lesson:

• VR Locomotion

9. Extension Activities

If you want to further develop your skills, explore new concepts, and improve your project, check out some of the extension activities below. Each one is tagged as [Easy], [Medium], [Difficult], or [Expert] to indicate the level of challenge and will also include a [Requires Programming] tag if relevant.

These are completely optional, but highly encouraged if you want to take your VR development to the next level.

1. Play with Directional Lighting [Easy]

Experiment with the directional light to achieve the shadow and color you want in your room:

• Try rotating the Directional Light about the X and Y axes

• Try adjusting the color of the Directional Light to match the color of light to the time of day

2. Device Simulator Practice [Medium]

Get comfortable using the basic functions of the device simulator:

• Refer to the instructions in the step above for how to set up and use the device simulator.

• Note: Remember to remove or disable the Simulator before running the app in your device.

3. Add a functioning clock [Expert] [Requires programming]
Add a clock on the wall that either (a) tells the current time for the user in their local timezone, or (b) tells the time you intend it to be your VR room world.

• Find a clock Prefab in the Course Library > Prefabs > Objects > Electronics folder.

• Hint: To access the system’s current time, use the DateTime.now property.