Legacy Documentation: Version 5.1
Unity Analytics Upgrade Instructions
VR Reference

VR Overview

Unity 5.1 contains built-in support for certain VR devices.

Overview

VR has traditionally been supported in Unity via external plugins. This had a few shortcomings:

  • Each VR device has a different plugin.
  • Plugins may conflict with each other.
  • Toggling between VR plugins to support multiple devices is a lot of extra work.
  • Each release of newer VR SDKs / Runtimes can break older games.
  • Toggling between VR and non VR mode is non trivial.
  • Lower level engine optimizations are not possible with plugin approach of two separate cameras.

Unity VR adds the ability to target VR devices from directly within Unity without the need for external plugins. It provides a base API and featureset with the goal of forward compatibility for devices and software. The provided API surface today is minimal by design, and will expand as we learn more about the needs of VR developers.

Enabling Unity VR Support

To enable VR for your game builds and the editor, set the “Virtual Reality Supported” option in Player Settings.

What happens when VR is enabled

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

Automatic stereo display

  • It is not required to have two Cameras for stereoscopic displays. Any camera that has no render texture is automatically rendered in stereo to your device. View and projection matrices are adjusted to account for field of view and head tracking.
    • Optimizations automatically occur to make it less expensive to draw frames twice (once for each eye).

Automatic Head-tracked Input

  • Head tracking and appropriate FOV is automatically applied to your camera (if your device is head mounted).
    • This happens by default because low latency head tracking is integral to a good VR experience.

Understanding the camera

  • The camera transform is overridden with the head-tracked pose.
    • If you want to move the camera, you must attach it as a child to another game object and then move the root game object.
    • You will need to adjust scripts that directly move the camera.
    • Think of the camera’s position and orientation as where you want your user to be looking in their neutral position.
    • If you need to reset the neutral position, use VR.InputTracking.Recenter().
    • You will need to adjust cameras that assume a specific field of view. Field of view is overridden by the VR Device.
    • Your scenes need to take into account that the camera can be pointed in any direction.
    • Depending on the VR Device, the camera can potentially move as well.
      • For now you must use Oculus’ SDK in order to obtain the movement volume or lock movement. This will be exposed through Unity in the future.
    • Many camera image effects don’t look right in VR. Ex. Depth of Field

Editor Mode

  • To enable VR for your game builds and the editor, set the “Virtual Reality Supported” option in Player Settings.
  • If your VR device supports Unity Editor mode (Ex. Oculus DK2), pressing play in the editor will allow you to test directly on your device.
    • Please note that there is some overhead to running in the editor and you may experience lag or judder if not rendering at the appropriate frame rate.
    • It is recommended to use “Maximize on Play” for the Game View to reduce editor rendering overhead.
    • The Unity profiler will tell you what your performance will be like when running outside of the editor. If you are trying to optimize to get the editor running well, make sure you enable editor profiling to see the editor overhead.

Standalone Builds: Choosing a VR Device

The option to start in VR mode is saved per computer, and defaults as VR off at the moment. This will change in the future.

To choose a VR Device, you can start Unity or the Unity application with the following command line argument:

-vrmode DEVICETYPE

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

Game.exe -vrmode oculus

Or, you can request a VR Device be loaded at runtime by setting the loaded device.

Once a VR device is loaded (loadedDevice returns something other than None), you can enable VR globally and start rendering to your device by setting VR.VRSettings.enabled to true.

VR Device Information

VRDevice.family is a string corresponding to the current VRSettings.loadedDevice. A family can have multiple models which have different characteristics. For example: Oculus has DK2, Gear VR, etc. The model can be accessed with VRDevice.model.

Unity Analytics Upgrade Instructions
VR Reference