Legacy Documentation: Version 5.4
Virtual Reality
VR reference

VR overview

Unity VR lets you target virtual reality devices directly from Unity, without any external plugins in projects. It provides a base API and feature set with compatibility for multiple devices. It has been designed to provide forward compatibility for future devices and software. The VR API surface is minimal by design, but will expand as VR continues to grow.

By using the native VR support in Unity, you gain:

  • Stable versions of each VR device
  • A single API interface to interact with different VR devices
  • A clean project folder with no external plugin for each device
  • The ability to include and switch between multiple devices in your applications
  • Increased performance (Lower-level Unity engine optimizations are possible for native devices)

Enabling Unity VR support

To enable VR for your game builds and the editor, open the Player Settings (menu: Edit > Project Settings > Player). Select Other Settings and check the Virtual Reality Supported checkbox. Set this for each build target. Enabling virtual reality support in a standalone build will not also enable the support for Android (or vice versa).

Use the Virtual Reality SDK list displayed below the checkbox to add and remove Virtual Reality Devices for each build target. The order of the list is the order that Unity will try to enable VR Devices at runtime. The first device that initializes properly will be the one enabled. This list order will be the same in the built player.

What happens when VR is enabled

When VR is enabled in Unity, a few things happen automatically:

Automatic rendering to a head-mounted display

All cameras in your scene are able to render directly to the head-mounted display (HMD). View and Projection matrices are automatically adjusted to account for head tracking, positional tracking and field of view.

It is possible to disable rendering to the HMD using the camera component’s stereoTargetEye property. Alternatively, you can set the camera to render to a render texture using the Target Texture property.

  • Using the stereoTargetEye property, you can also set the camera to only render a specific eye to the HMD. This can be useful for special effects such as a sniper scope or stereoscopic videos. To achieve this, add two cameras to the scene: one targeting the left eye, the other targeting the right eye. Set layer masks to tweak what is sent to each eye.

Automatic head-tracked input

Head tracking and the appropriate Field of View (FOV) is automatically applied to the camera if your device is head-mounted. You can manually set the FOV to a specific value, but you will not be able to set the Camera’s transform values directly. See the Understanding the Camera section below to learn more.

Head tracking and positional tracking are automatically applied, so that the position and orientation most closely matches the user’s position and orientation before the frame is rendered. This gives a good VR experience, and prevents the user from experiencing nausea.

Understanding the camera

The camera transform is overridden with the head-tracked pose. To move or rotate the camera, attach it as a child of another GameObject. This makes it so that all transform changes to the parent of the camera will affect the camera itself. This also applies to moving or rotating the camera using a script.

Think of the camera’s position and orientation as where the user is looking in their neutral position.

There are differences between seated and room-scale VR experiences:

  • If your device supports a room-scale experience, the camera’s starting position will be the center of the user’s play space.
  • Using the seated experience, you can reset cameras to the neutral position using VR.InputTracking.Recenter().

Each camera that is rendering to the device automatically overrides the field of view of the camera with the field of view your user has input in the software settings for each VR SDK. You can override this field of view value through script at runtime to set a custom field of view specific to your application.

Editor Mode

If your VR device supports Unity Editor mode, pressing Play in the Editor lets you test directly on your device.

The left eye is rendered to the Game View window if you have stereoTargetEye set to left or both. The right eye is rendered if you have stereoTargetEye set to right.

  • There is no automatic side-by-side view of the left and right eyes.
  • To see a side-by-side view in the Game View, create two cameras, set one to the left and one to the right eye, and set the viewport of display them side by side.

Note that there is overhead to running in the Editor, and you may experience lag or judder. The Unity IDE needs to render each window, so use “Maximize on Play” for the Game View to reduce editor rendering overhead.

  • The Unity Profiler is a helpful tool to get an idea of what your performance will be like when running outside of the Editor. However, the profiler itself also has overhead.

The best way to review your performance is to create a build on your target platform and run it directly. You will see the best performance when running a non-development build, but development builds will allow you to connect the Unity profiler for better performance profiling.

Built applications: Choosing startup device

Your built application initializes and enables devices in the same order as the Player Settings list (see Enabling VR Support above). Devices not present in the list at build time are not available in the final build.

If you want to start with a device that isn’t at the top of the list, you can pass a command line argument to the executable to force a specific device at startup. Again, this device needs to have been included in the list prior to building the application.

The command line argument used to startup a specific device is:

-vrmode DEVICETYPE

where DEVICETYPE is one of the names from the supported VR devices list.

Example: MyGame.exe -vrmode oculus

Hardware and software recommendations for VR development in Unity

Hardware

Achieving a frame rate similar to your target HMD is essential for a good VR experience. This must match the refresh rate of the display used in the HMD. If the frame rate drops below the HMD’s refresh rate, it is particularly noticeable and often leads to nausea for the player.

Refresh rates for VR devices:

VR Device Refresh Rate
Gear VR 60hz
Oculus CV1 90hz
Vive 90hz

Software

  • Windows: Windows 7, 8, 8.1, and Windows 10 are all compatible.

  • Android: Android OS Lollipop 5.1 or higher.

  • OS X: OSX 10.9+ with the Oculus 0.5.0.1 runtime. However, Oculus have paused development for OS X, so use Windows for native VR functionality in Unity.

  • Graphics card drivers: Make sure your drivers are up to date. Every device is keeping up with the newest drivers, so older drivers may not be supported.

  • Oculus Runtime: Runtime 0.8 or higher.

Virtual Reality
VR reference