VR Template Quick Start Guide

Unity’s VR Project Template provides a starting point for virtual reality development in Unity. The template configures project settings, pre-installs the right packages, and includes various pre-configured Example Assets to demonstrate how to set up a project that is ready for VR. Please refer to the XR Project Setup documentation for additional information.

The VR Template uses the following Unity features:

• XR Interaction Toolkit - A high-level, component-based, interaction system for creating XR experiences. It provides a framework that makes 3D and UI interactions available from Unity input events.
• OpenXR - A scalable package that enables cross-platform support for multiple hardware environments.

Using the Sample Scene

The VR Template contains a Scene named SampleScene located in Assets/Scenes. This scene’s Hierarchy is pre-configured with GameObjects that allow your application to manage controller and head tracking, locomotion, and interaction with spatial UI and virtual objects.

You can use this scene as a reference, or you can remove the example Assets from it and use it as a starting point for your own Project.

Sample Scene Hierarchy Overview

XR Origin

The XR Origin is currently configured to support both hands and controllers. There is a controllers only XR Origin variant named Complete XR Origin Set Up Variant which can be found at Assets/VRTemplateAssets/Prefabs/Setup.

Interactables

There are various objects within the scene that the user is able to interact with. In XRI, they are called interactables. The grab interactable allows a user to pick up a GameObject using either a direct or ray interactor. Grab interactables need a Rigidbody and a Collider to define the interactable area.

In addition, the Affordance system provides feedback for the user with visual and auditory cues. This requires the use of the XR Interactable Affordance State Provider with a specified interactable source. For the interactables included in the Sample scene, there is an Audio Affordance Receiver and a Color Affordance Receiver already set up.

Color Affordance Receiver Example

The color affordance receiver applies colors from the affordance theme datum to material property block color property. This allows you to define different color to apply for different interaction states.

Audio Affordance Receiver Example

The audio affordance receiver plays audio clips stored in the audio affordance theme datum. It requires an audio source. This allows you to define different audio clips to be played for different interaction states.

These Affordance Receivers are driven by Affordance System Themes found in Assets > VR Template Assets > Themes.

Edge Color Affordance Theme Example

This theme is used to define colors to apply to materials based on the interaction state. The animation curve is used to lerp the color between animation states.

Audio Affordance Theme Example

This theme is used to define the audio clips to play based on interaction state. You can configure different clips for state entered or state exited.

Teleportation

Teleportation allows users to move within the Sample Scene without experiencing the discomfort common while walking in VR. Teleportation Areas designate specific surfaces for the user to move. The teleportation area is configured with specific colliders from the scene.

Teleportation Area

Teleport Anchors, on the other hand, constrain the user’s view in terms of position and rotation while teleporting. One is already set up for you in the scene.

Teleportation Anchor

Spatial UI

The Sample Scene contains various world space UI examples which allows both near and far interactions with UI elements such as sliders, dropdown menus, toggles, and buttons. In addition, users have the ability to move the canvas in space with the Spatial UI Panel prefab, which affords the ability to grab the canvas by either the header or handle at the bottom of the canvas. Billboarding with the Turn To Face component is on the prefab by default, with the positional transformation of the canvas being determined by the direct/ray interactor.

Spatial UI Example

Project Configuration

Various presets are used to accommodate graphics & rendering requirements for different platforms. By selecting the target platform in the Build Settings, i.e. Windows, Mac, Linux or Android, different URP Config Settings are automatically updated for the user. The presets can be found in Assets/Settings/Project Configuration.

For Android, the Android Preset and Performance URP Config assets provide a good baseline of graphics settings for low powered headsets such as the Quest.

Additional information can be found in the URP documentation.

For standalone PC VR, the Standalone Preset and Quality URP Config assets allow for a higher quality experience.

In addition, by selecting the target platform in Build Settings, OpenXR feature groups and interaction profiles are preconfigured. By default, the Android build target updates the settings for Meta Quest support. You can also add hand support by enabling Hand Tracking Subsystem and Meta Hand Tracking Aim. Additional information can be found in the OpenXR documentation.

For standalone PC VR, numerous interaction profiles are already configured for the user. If you don't see your platform listed, add your interaction profile manually by clicking the + button.

Graphics APIs

The last setting you may need to adjust if you are using the Android build target is the Graphics API. By default, the VR Template uses the Vulkan graphics API for compatibility and performance reasons, including reduced build times. If you are targeting a device that does not fully support the Vulkan API, you may have to add OpenGLES3 to the list:

1. Go to Edit > Project Settings.
2. Click Player in the left-hand pane.
3. Click on the Android tab.
4. Expand Other Settings.
5. Locate the Graphics APIs list and click the + symbol.
6. In the drop-down click on OpenGLES3 to add it to the list.
7. Click on File > Save Project to save these changes.

Android XR Support (Public Experimental Release)

Android XR Documentation

If you want to change the configuration to deploy to an Android XR device, there are some additional setup options (while the package is still in a public experimental state).

Add the Android XR OpenXR package to your newly-created project

• The easiest option is to click the following link to automatically bring up the Package Manager package install window: com.unity.xr.androidxr-openxr.

• You may also manually install the package by opening the Package Manager. Go to Window > Package Manager.

  From this window you can install the package in one of two ways:

  • The first option is to Install package by name....

  In Package Manager, click the plus symbol (+) in the upper left corner and choose Install package by name... from the dropdown.

  

  In the box that appears, enter the Android XR package name (com.unity.xr.androidxr-openxr), leave the version field blank, and press the Install button.

  

  • The second option is to install the Android XR package Install package from tarball....

  In Package Manager, click the plus symbol (+) in the upper-left corner and choose Install package from tarball... from the dropdown. In the file window, navigate to where you have previously downloaded .tgz file for the Android XR package.

  

Project Configuration (Android XR)

Once the package is installed, the Project Settings must be configured to support the newly added package. Navigate to Project Settings by going to Edit > Project Settings.

In the Project Settings window, navigate to the XR Plug-in Management settings in the left-hand pane. Under the Android build target, enable the Android XR feature group option under the OpenXR option in the Plug-in Providers list.

In the Project Settings window navigate to the XR Plug-in Management > OpenXR settings window. Under the Android build target, the settings to support both hands and controllers should be configured for the Android XR platform:

Note

If you do not see the Android XR option in the OpenXR Feature Groups, make sure to enable the Android XR feature group in the XR Plug-in Management settings window. This step is documented above.

Scene Modification

For hands support, navigate to Assets/VRTemplateAssets/Android XR/ and add Hands Permissions Manager prefab to the scene.

The Hands Permissions Manager should have the android.permission.HAND_TRACKING permission request enabled and configured to call HandsManagerSubsystem.EnableHandTracking when permissions are granted.