Oculus Utilities for Unity

5.x Developer Guide

Version 0.1.3.0 Beta

2|Introduction|Unity

Copyrights and Trademarks

2016 Oculus VR, LLC. All Rights Reserved.

OCULUS VR, OCULUS, and RIFT are trademarks of Oculus VR, LLC. (C) Oculus VR, LLC. All rights reserved.
BLUETOOTH is a registered trademark of Bluetooth SIG, Inc. All other trademarks are the property of their
respective owners. Certain materials included in this publication are reprinted with the permission of the
copyright holder.

2||

Unity|Contents|3

Contents
Introduction.......................................................................................................... 5
Compatibility and Requirements....................................................................................................................... 5
Downloading Utilities for Unity......................................................................................................................... 7
Preparing for Development: PC SDK................................................................................................................7
Preparing for Development: Mobile SDK......................................................................................................... 8

Getting Started.................................................................................................... 9
Unity VR Support............................................................................................................................................... 9
Importing the Oculus Utilities Package.............................................................................................................9
Importing Sample Applications: Mobile SDK................................................................................................. 10
Migrating to Utilities from the Integration Package....................................................................................... 11

A Detailed Look at Oculus Utilities for Unity.....................................................13

Contents........................................................................................................................................................... 13
Prefabs..............................................................................................................................................................14
Unity Components........................................................................................................................................... 16
Oculus Mobile SDK Examples.........................................................................................................................18

OVRInput............................................................................................................ 20
OVRInput Usage.............................................................................................................................................. 20
Touch Input Mapping......................................................................................................................................23
Xbox Input Handling....................................................................................................................................... 24

Configuring for Build......................................................................................... 26

PC Build Target: Microsoft Windows and Mac OS X..................................................................................... 26
Build Settings and Player Settings.............................................................................................................26
Quality Settings.......................................................................................................................................... 28
Running the Build.......................................................................................................................................29
Mobile Build Target: Android......................................................................................................................... 29
Build Settings............................................................................................................................................. 30
Player Settings............................................................................................................................................ 30
Running the Build.......................................................................................................................................31

Best Practices: Mobile....................................................................................... 32

Design Considerations.....................................................................................................................................32
Best Practices...................................................................................................................................................32
General CPU Optimizations.............................................................................................................................33
Rendering Optimization...................................................................................................................................33
Unity Profiling Tools........................................................................................................................................ 35

Troubleshooting and Known Issues...................................................................38

General Issues..................................................................................................................................................38
PC..................................................................................................................................................................... 38
OS X.................................................................................................................................................................39
Mobile.............................................................................................................................................................. 39
Contact Information......................................................................................................................................... 40

Tutorial: Build a Simple VR Unity Game............................................................41

4|Contents|Unity

Installation and Preparation.............................................................................................................................41

Modify Roll-a-ball for VR................................................................................................................................. 42
Build and Play..................................................................................................................................................44

Unity-SDK Version Compatibility....................................................................... 45

Release Notes.................................................................................................... 46
0.1
0.6
0.6
0.5
0.4

Beta Utilities for Unity Release Notes.......................................................................................................46

Unity Legacy Integration Release Notes...................................................................................................48
PC Unity Integration Release Notes......................................................................................................... 52
Mobile Unity Integration Release Notes...................................................................................................52
Mobile Unity Integration Release Notes...................................................................................................53

Unity|Introduction|5

Introduction
This guide describes developing Unity 3D games and applications for VR devices with the Oculus PC and
mobile SDKs.
The Utilities package is for use with Unity Professional and Personal editions versions 5.x. Projects using
Unity 4 should use our Unity 4.x Legacy Integration package instead. We strongly recommend developers
beginning new projects use Unity 5.1+ and our Utilities package. For more information on version compatibility,
see Compatibility and Requirements.
This guide covers:

Getting started
Downloading and installing the Utilities package
Contents of the Utilities package
Input Mapping
How to use the provided samples, assets, and sample applications
Configuring Unity VR projects for build to various targets
Building a simple VR Unity game (tutorial)

Most information in this guide applies to the use of the Utilities package with either the Oculus PC or Mobile
SDKs. Any exceptions are clearly indicated where they occur (e.g., the Moonlight folder in OVR contains assets
designed for mobile development).
When developing for both Rift and mobile platforms, keep in mind that the requirements for PC and mobile
VR applications differ substantially. If you would like to generate builds for both PC and mobile from a single
project, it is important to follow the more stringent mobile development best practices.
Unity First-Party VR Support
With Unity 4, developers used the Oculus Integration package to import Oculus VR camera and controller
prefabs. In Unity 5.1+, developers may substitute a stereoscopic VR camera with built-in orientation and
positional tracking for their main camera by selecting the Virtual Reality Supported check box in Player Settings.
Unlike the Legacy Integration, which was necessary for VR support in Unity 4, the Utilities package is an optional
supplement with useful material to support development.
See Unity VR Support for more information.

Compatibility and Requirements

System and Hardware Requirements
Please review the relevant documentation to be sure that you are using supported hardware and that your
development environment and devices are configured and set up properly:
PC SDK: Oculus Developer Guide
Mobile SDK: Setup Guide
Before beginning Unity development, you should be able to run the Oculus SDK Unity sample applications.

6|Introduction|Unity

Note: This integration does not currently support Windows 10.

Unity Version Compatibility

Unity 5.1+ provides support for virtual reality development with the Oculus Rift and Samsung Gear VR,
optionally supplemented by the Oculus Utilities for Windows package. Projects built with the Oculus Unity
Legacy Integration are not compatible with Unitys VR support.
Unity 4 VR support is provided by assets included with the Oculus Unity Legacy Integration package.
Developers using Unity 4 and the Legacy Integration should start planning for migration to Unity 5. We are
maintaining the Unity Integration for developers who are not ready to upgrade, but it will be discontinued at
some point in the future.
If you are starting a new project, we strongly recommend using the appropriate version of Unity 5.1 and the
Utilities package.
Unity Version

Recommended
Release

Description / Oculus Compatibility

Unity 5.1+

Unity 5.3.1p4

Provides first-party support for virtual reality development. For

optional supplementary plugins and scripts, use the latest Oculus
Utilities for Unity.
SDK Examples are available for use with our Mobile SDK.
(download separately)

Unity 5.0

n/a

Oculus does not support this Unity version.

Unity 4

Unity 4.7.0f1

VR support is enabled by importing custom assets. Use the latest

Oculus Legacy Integration.

For more details on the relationship between past and present Unity versions, Oculus PC and Mobile SDKs, and
Oculus Unity Integration and Utilities packages, see Unity-SDK Version Compatibility.
Oculus Runtime (PC Only)
For PC SDKs 0.7 through 1.0, each SDK version only guarantees support for the current and previous runtime
version, e.g., PC SDK 0.7 is only guaranteed to work with runtime versions 0.6, 0.6.0.1, and 0.7.
Utilities and Legacy Integration versions do not depend on specific runtimes, and will run with reduced
functionality on older Unity Versions and PC runtimes.
Unity Version

Integration/Utilities Version

Compatible PC Runtime

Unity 4.7.0f1

Legacy Integration 0.8.0.0

0.8 and 0.7

5.3.1p4

Utilities 0.1.3.0

0.8 and 0.7

Unity Personal and Professional Licenses

There are noteworthy feature support differences between Unity licenses. Please review the limitations cited
below as well as the license comparison on Unitys website before committing considerable resources to one
path. Your license choice will depend largely on the performance characteristics and distribution needs of your
app.

Unity|Introduction|7

A feature set comparison between Unity Professional and Personal editions may be found here: http://
unity3d.com/unity/licenses
Gamepad Controller
You may wish to have a compatible gamepad controller for use with the supplied demo applications, such
as the Xbox 360 controller for Windows, an HID-compliant game controller for Mac, or a Moga Pro or other
compatible controller for Gear VR.

Downloading Utilities for Unity

All Oculus Unity development materials are available for download at our Developer site (requires login):
https://developer.oculus.com/downloads/
Utilities Package Contents
A Utilities package containing scripts, assets, sample scenes, et cetera
Project Settings assets
Also Available
Additional development resources are available separately from our Downloads page.
SDKExamples designed for use with the Mobile SDK (source)
Oculus Spatialization Plugin for Unity (included with Oculus Audio SDK)
Oculus Utilities for Unity supplements Unitys core VR support with additional development resources, including
assets, scripts, and sample scenes to assist with development.
SDK Examples is a resource for mobile developers that includes Unity example scenes illustrating the use
of common resources such as menus, crosshairs, and more. For Utilities for Unity 5x, they are available for
download separately from our Downloads page here: https://developer.oculus.com/downloads/. For our
Unity 4x Legacy Integration, they are included in the Mobile SDK folder SDKExamples. See Oculus Mobile
SDKExamples for more information.

Preparing for Development: PC SDK

When developing for PC, we recommend beginning with the Oculus Developer Guide and theOculus Best
Practices Guide, which includes information and guidelines for developing great VR experiences, and should be
considered a go-to reference when designing your Oculus-ready games.
Recommended Configuration
We recommend the following settings in your project:
On Windows, enable Direct3D 11. D3D 11 exposes the most advanced VR rendering capabilities. D3D 9
and OpenGL do not currently work in VR with Unity.
Use the Linear Color Space. Linear lighting is not only more correct for shading, it also causes Unity to
perform sRGB read/write to the eye textures. This helps reduce aliasing during VR distortion rendering,
where the eye textures are interpolated with slightly greater dynamic range.

8|Introduction|Unity

Never clone displays. When the Rift is cloned with another display, the application may not vsync properly.
This leads to visible tearing or judder (stuttering or vibrating motion).

Preparing for Development: Mobile SDK

This guide describes setup requirements for Oculus mobile VR development with Unity.
Android SDK Setup and Oculus Mobile SDK
The Android SDK is required for mobile development with Unity. However, most Unity developers do not need
to install Android Studio or NDK. Unity developers should follow the instructions in our Device Setup guide,
and install the Java Development Kit (JDK) and Android SDK before beginning development. See Unitys
Getting Started with Android Development for more information.
Note: You must download the Oculus Mobile SDK if you wish to use OVRMonitor.
When developing for mobile, please be sure to fully review all of the relevant performance and design
documentation, especially the Unity Best Practices: Mobile. Mobile apps are subject to more stringent
limitations and requirements and computational limitations which should be taken into consideration from the
ground up.
Application Signing
Mobile applications require two different signatures at different stages of development. Be sure to read the
Application Signing section of the Mobile SDK documentation for more information.
Application Entitlement Checking
Entitlement checking, used to protect apps from unauthorized distribution, is disabled by default in Unity. For
more information and instructions, see "VrPlatform Entitlement Checks" in the Mobile SDK documentation.

Unity|Getting Started|9

Getting Started
This section describes steps taken to begin working in Unity.

Unity VR Support
Unity 5.1 and later offer first-party virtual reality support, toggled by the Virtual Reality Supported checkbox in
the Other Settings > Configuration tab of Player Settings.
When Unity virtual reality support is enabled, any camera with no render texture is automatically rendered in
stereo to your device, and positional and head tracking is automatically applied to your camera, overriding your
cameras transform.
When Unity applies head tracking to the VR camera, it applies it within the reference frame of the camera's
local pose when the application starts. If you are using OVRCameraRig, that reference frame is defined by the
TrackingSpace GameObject, which is the parent of the CenterEyeAnchor GameObject that has the Camera
component.
The Unity Game View preview does not apply lens distortion. The image corresponds to the left eye buffer and
uses simple pan-and-scan logic to correct the aspect ratio.
For detailed information and instructions for using Unitys VR support, see the Virtual Reality section of the Unity
Manual.
Note: Unitys VR support is not compatible with previous Oculus Unity Integrations; see The Oculus
Utilities Package and Unity for more information.

Importing the Oculus Utilities Package

The Oculus Utilities Unity Package includes assets, scripts, and sample scenes to assist with development.
Delete Previously-Imported Assets
If you have previously imported a Unity integration package, delete all Oculus Integration content before
importing the new Unity package. Be sure to close the Unity Editor, then navigate to your Unity project folder
and delete the following:
Folder

Content to Delete

Assets/Plugins

Oculus.*
OVR.*

Assets/Plugins/
Android/

*Oculus*
AndroidManifest.xml
*vrapi*
*vrlib*

10|Getting Started|Unity

Folder

Content to Delete
*vrplatlib*

Assets/Plugins/x86/

Oculus.*
OVR.*

Assets/Plugins/
x86_64/

Oculus.*
OVR.*

Note: Be sure to delete OculusPlugin.dll in Assets/Plugins/x86_64 and OculusUnityPatcher*.exe in

Assets/OVR/Editor in addition to all other specified files.
Unity Project
If you are already working in a Unity project, save your work before beginning.
Otherwise, create a new project into which you will import the Oculus assets:
1.
2.
3.
4.

From the Unity menu, select File > New Project.

Click the Browse button and select the folder where the Unity project will be located.
Make sure that the Setup defaults for: field is set to 3D.
You do not need to import any standard or pro Unity asset packages, as the Oculus Utilities package is fully
self-contained.
5. Click the Create button. Unity will reopen with the new project loaded.
Utilities Package
Note: If you are importing the Utilities package into a project that previously used our legacy
Integration package, see Migrating to Utilities from the Integration Package for important steps to take
before importing the custom assets package.
To import the package into Unity, select Assets > Custom Package... and select the Utilities for
Unity .unityPackage to import the assets into your new project. Alternately, you can locate the .unityPackage
file in your file system and double-click to launch.
When the Importing package dialog box opens, leave all of the boxes checked and select Import. The import
process may take a few minutes to complete.
Project Settings (mobile only)
The mobile Utilities package includes a Project Settings folder which provides default settings for a VR mobile
application. You may manually copy these files to your [Project]/Assets/ProjectSettings folder.

Importing Sample Applications: Mobile SDK

In this section we'll describe how to import sample Unity application source into Unity, using BlockSplosion as
an example.
Note: For Rift development, the Room sample application is included as a scene in the Utilities
package.

Unity|Getting Started|11

If you are already working in a Unity project, save your work before beginning.
To import the Utilities package into Unity, select Assets > Custom Package... and select
BlockSplosion.unitypackage to import the assets into your new project. Alternately, you can locate the
BlockSplosion.unitypackage file and double-click to launch, which will have the same effect.
Each sample application project includes a ProjectSettings folder which provides default settings for the VR
mobile application. Copy these files to your [Project]/Assets/ProjectSettings folder.
The import process may take a few minutes to complete.

Migrating to Utilities from the Integration Package

Moving to Unity 5.1 is a substantial upgrade for VR development, and we recommend carefully choosing your
time frame for making the update. There is always risk in moving early to a new major release that you may
encounter problems related to VR performance or otherwise.
Please let us know about any issues you encounter in the Oculus Unity forums, and keep your eye out for
updates.
For details on implementing Unity's first-party VR support, see the Unity manual: http://docs.unity3d.com/
Manual/VROverview.html
Delete Previously-Imported Assets
If you have previously imported a Unity integration package, delete all Oculus Integration content before
importing the new Unity package. For detailed instructions, see Importing the Oculus Utilities Package.
Upgrade Procedure
1. Replace any usage of OVRManager.instance.virtualTextureScale or
OVRManager.instance.nativeTextureScale with UnityEngine.VR.VRSettings.renderScale. The value of
renderScale is equal to nativeTextureScale * virtualTextureScale. If you set renderScale to a value that is less
than or equal to any value it has had since the application started, then virtual texture scaling will be used. If
you increase it higher, to a new maximum value, then the native scale is increased and the virtual scale is set
to 1.
2. Replace any usage of OVRManager.instance.eyeTextureAntiAliasing with
UnityEngine.QualitySettings.antiAliasing. Instead of multisampling the back-buffer when VR is enabled, Unity
multisamples the eye buffers.
3. Remove any usage of OVRManager.instance.timeWarp and OVRManager.instance.freezeTimeWarp.
TimeWarp is always on and cannot be frozen.
4. Do not assume there are Cameras on OVRCameraRig.leftEyeAnchor or rightEyeAnchor. Instead
of calling GetComponent<Camera>(), use Camera.main or, for backward compatibility, use
OVRCameraRig.leftEyeCamera or rightEyeCamera.
5. Move any scripts, image effects, tags, or references from the Cameras on OVRCameraRig.leftEyeAnchor and
rightEyeAnchor to the one on centerEyeAnchor.
6. Remove any usage of OvrCapi.cs. The CAPI C# binding is no longer available. If you need to access CAPI,
use UnityEngine.VR.VRDevice.GetNativePtr() to get an ovrHmd pointer and then pass it to a native plugin
that uses the Oculus SDK corresponding to your Unity version. For more on which Unity versions correspond
to which SDKs, see "Integration Versions" in Compatibility and Requirements.
Importing Utilities Package into Legacy Projects
The legacy Oculus Unity Integration used a separate Camera component on each eye anchor. Oculus Utilities
for Unity uses single camera on the center eye anchor. If the Oculus Utilities package is imported into an old

12|Getting Started|Unity

project built with the legacy Unity integration, editor scripts will patch up old OVRCameraRig GameObjects and
enable PlayerSettings.virtualRealitySupported, so the project should work without further action.
Note: Don't forget to move any scripts, image effects, tags, or references from the left and right eye
anchors to the center eye anchor as noted above.

Unity|A Detailed Look at Oculus Utilities for Unity|13

A Detailed Look at Oculus Utilities for

Unity
This section examines the Utilities package, including its directory structure, the supplied prefabs, and several
key C# scripts.
Note: There may be minor differences between the contents of the Utilities packages provided for PC
development and the version bundled with the mobile SDK.

Contents
OVR
The contents of the OVR folder in OculusUtilities.unitypackage are uniquely named and should be safe to
import into an existing project.
The OVR directory contains the following subdirectories:
Editor

Contains scripts that add functionality to the Unity Editor, and enhance several C#
component scripts.

Materials

Contains materials that are used for graphical components within the Utilities package,
such as the main GUI display.

Meshes

Contains Meshes that are required by some OVR scripts, such as the TrackerBounds.

Moonlight

Contains classes designed for Gear VR development. It holds sub-folders with mobile
equivalents of all top-level folders (Editor, Materials, Prefabs, et cetera).

Prefabs

Contains the main Unity prefabs that are used to provide the VR support for a Unity
scene: OVRCameraRig and OVRPlayerController.

Scenes

Contains sample scenes.

Scripts

Contains the C# files that are used to tie the VR framework and Unity components
together. Many of these scripts work together within the various Prefabs.

Textures

Contains image assets that are required by some of the script components.

Note: We strongly recommend that developers not directly modify the included OVR scripts.

Plugins
The Plugins folder contains the OVRGamepad.dll, which enables scripts to communicate with the Xbox
gamepad on Windows (both 32 and 64-bit versions).

14|A Detailed Look at Oculus Utilities for Unity|Unity

This folder also contains the plugin for Mac OS: OVRGamepad.bundle.

Prefabs
The current integration for adding VR support into Unity applications is based on two prefabs that may be
added into a scene:
OVRCameraRig
OVRPlayerController
To use, simply drag and drop one of the prefabs into your scene.
OVRCameraRig
OVRCameraRig replaces the regular Unity Camera within a scene. You can drag an OVRCameraRig into your
scene and you will be able to start viewing the scene with the Gear VR and Rift.
Note: Make sure to turn off any other Camera in the scene to ensure that OVRCameraRig is the only
one being used.
Figure 1: OVRCameraRig and OVRManager

OVRCameraRig contains one Unity camera, the pose of which is controlled by head tracking; two anchor
GameObjects for the left and right eyes; and one tracking space GameObject that allows you to fine-tune the
relationship between the head tracking reference frame and your world. The rig is meant to be attached to a
moving object, such as a character walking around, a car, a gun turret, et cetera. This replaces the conventional
Camera.
The following scripts (components) are attached to the OVRCameraRig prefab:
OVRCameraRig.cs
OVRManager.cs

Unity|A Detailed Look at Oculus Utilities for Unity|15

OVRPlayerController
The OVRPlayerController is the easiest way to start navigating a virtual environment. It is basically an
OVRCameraRig prefab attached to a simple character controller. It includes a physics capsule, a movement
system, a simple menu system with stereo rendering of text fields, and a cross-hair component.
To use, drag the player controller into an environment and begin moving around using a gamepad, or a
keyboard and mouse.
Note: Make sure that collision detection is active in the environment.
Two scripts (components) are attached to the OVRPlayerController prefab:
OVRPlayerController.cs
OVRGamepadController.cs
Figure 2: OVRPlayerController

16|A Detailed Look at Oculus Utilities for Unity|Unity

Unity Components
The following section gives a general overview of what each of the scripts within the Scripts folder does.
OVRCameraRig
OVRCameraRig is a component that controls stereo rendering and head tracking. It maintains three child
"anchor" Transforms at the poses of the left and right eyes, as well as a virtual "center" eye that is halfway
between them.
This component is the main interface between Unity and the cameras. This is attached to a prefab that makes it
easy to add comfortable VR support to a scene.
Important: All camera control should be done through this component. You should understand this script when
implementing your own camera control mechanism.
Mobile and PC Public Members
Updated Anchors

Allows clients to filter the poses set by tracking. Used to modify or ignore positional
tracking.

GameObject Structure
TrackingSpace

A GameObject that defines the reference frame used by tracking. You can move this
relative to the OVRCameraRig for use cases in which the rig needs to respond to IR
sensor input. For example, OVRPlayerController changes the position and rotation of
TrackingSpace to make the character controller follow the yaw of the current head pose.

OVRManager
OVRManager is the main interface to the VR hardware. It is a singleton that exposes the Oculus SDK to Unity,
and includes helper functions that use the stored Oculus variables to help configure camera behavior.
This component is added to the OVRCameraRig prefab. It can be part of any application object. However, it
should only be declared once, because there are public members that allow for changing certain values in the
Unity inspector.
OVRManager.cs contains the following public members:
Table 1: Mobile and PC Public Members
Monoscopic

If true, rendering will try to optimize for a single viewpoint rather than rendering once
for each eye. Not supported on all platforms.

Table 2: PC-Only Public Members

Use Position Tracking

Disables the IR sensor and causes head position to be inferred from the current rotation
using the head model. To fully ignore tracking or otherwise modify tracking behavior,
see OVRCameraRig.UpdatedAnchors above

Unity|A Detailed Look at Oculus Utilities for Unity|17

Reset Tracker On Load

This value defaults to True. When turned off, subsequent scene loads will not reset the
sensor. This will keep the sensor orientation the same from scene to scene, as well as
keep magnetometer settings intact.

Helper Classes
In addition to the above components, your scripts can always access the HMD state via static members of
OVRManager.
OVRDisplay

Provides the pose and rendering state of the HMD.

OVRTracker

Provides the pose, frustum, and tracking status of the infrared tracking camera.

Utilities
OVRPlayerController

OVRPlayerController implements a basic first-person controller for the VR framework. It

is attached to the OVRPlayerController prefab, which has an OVRCameraRig attached to
it.
The controller will interact properly with a Unity scene, provided that the scene has
collision detection assigned to it.
OVRPlayerController contains a few variables attached to sliders that change the physics
properties of the controller. This includes Acceleration (how fast the player will increase
speed), Dampening (how fast a player will decrease speed when movement input is not
activated), Back and Side Dampen (how much to reduce side and back Acceleration),
Rotation Amount (the amount in degrees per frame to rotate the user in the Y axis)
and Gravity Modifier (how fast to accelerate player down when in the air). When HMD
Rotates Y is set, the actual Y rotation of the cameras will set the Y rotation value of the
parent transform that it is attached to.
The OVRPlayerController prefab has an empty GameObject attached to it called
ForwardDirection. This GameObject contains the matrix which motor control bases it
direction on. This GameObject should also house the body geometry which will be seen
by the player.

OVRGamepadController

OVRGamepadController is an interface class to a gamepad controller. It is crossplatform and works on the Samsung EI-GP20 Gamepad for Android if you include
InputManager.asset in your project.
On Windows systems, the gamepad must be XInput-compliant. To use the Xbox
controller on a Mac, install the TattieBogle driver.

OVRGridCube

OVRGridCube is a helper class that shows a grid of cubes when activated. Its main
purpose is to be used as a way to know where the ideal center of location is for the
user's eye position. This is especially useful when positional tracking is activated. The
cubes will change color to red when positional data is available, and will remain blue if
position tracking is not available, or change back to blue if vision is lost.

OVRTrackerBounds

Warns players when the HMD moves outside the trackable range.

18|A Detailed Look at Oculus Utilities for Unity|Unity

GameObject Structure
ForwardDirection

An empty GameObject attached to the OVRPlayerController prefab containing the

matrix upon which motor control bases its direction. This GameObject should also
house the body geometry which will be seen by the player.
See TrackingSpace in OVRCameraRig for more information

Oculus Mobile SDK Examples

The SDK Examples project demonstrates useful scenarios and functionality.
To download, select Platform: Game Engines from our Downloads page here: https://developer.oculus.com/
downloads/
To import SDKExamples into Unity, begin by creating a new, empty project. Then select Assets >Import
Package > Custom Package... and select SDKExamples.unityPackage to import the assets into your project.
Alternately, you can locate the SDKExamples.unityPackage and double-click to launch, which will have the
same effect.
Once imported, replace your Unity project's ProjectSettings folder with the ProjectSettings folder included with
SDKExamples.
Note: If you don't replace the ProjectSettings folder, imported scenes will show console errors.

You will find the following sample scenes located in Assets/Scenes:

Trivial

An empty scene with one cube and a plain Unity camera.

Unity|A Detailed Look at Oculus Utilities for Unity|19

Room

A cubic room formed from six cubes enclosing an OVRPlayerController.

Cubes

A 3D array of cubes and an OVRCameraRig.

The example scripts are located in Assets/OVR/Moonlight/:

Crosshair3D.cs

Detailed code for how to create judder-free crosshairs tied to the camera view.

StartupSample.cs

Example code for loading a minimal-scene on startup while loading the main scene in
the background.

TimeWarp30HzSample.cs

Example code for setting up TimeWarp to support 30Hz apps as well as toggling
Chromatic Aberration Correction and Monoscopic Rendering on and off.

HomeMenu.cs

Example code for an animated menu.

HomeButton.cs

Example code which provides button commands (used in conjunction with

HomeMenu.cs).

HomeBattery.cs

Example code for using the SDK Battery Level API and interactively modifying a visual
indicator.

MoviePlayerSample.cs

Example code and documentation for how to play an in-game video on a textured
quad using Android MediaPlayer (mobile) or Unity's native media rendering (PC). Note:
libOculusMediaSurface currently works with GLES2 only.

OVRChromaticAberration.csDrop-in component for toggling chromatic aberration correction on and off for Android.
OVRDebugGraph.cs

Drop-in component for toggling the TimeWarp debug graph on and off. Information
regarding the TimeWarp Debug Graph may be found in the TimeWarp technical note in
the Mobile SDK documentation.

OVRModeParms.cs

Example code for de-clocking your application to reduce power and thermal load as
well as how to query the current power level state.

OVRMonoscopic.cs

Drop-in component for toggling Monoscopic rendering on and off for Android.

OVRResetOrientation.cs

Drop-in component for resetting the camera orientation.

OVRWaitCursor.cs

Helper component for auto-rotating a wait cursor.

OVRPlatformMenu.cs

Helper component for detecting Back Key long-press to bring-up the Universal Menu
and Back Key short-press to bring up the Confirm-Quit to Home Menu. Additionally
implements a Wait Timer for displaying Long Press Time. For more information on
interface guidelines and requirements, please review Interface Guidelines and Universal
Menu in the Mobile SDK documentation.

20|OVRInput|Unity

OVRInput
Note: OVRInput is now our supported API for PC and Mobile input handling. OVRInputControl and
OVRGamepadController are now deprecated and will be removed in a later version.
OVRInput exposes a unified input API for multiple controller types. It may be used to query virtual or raw
controller state, such as buttons, thumbsticks, triggers, and capacitive touch data. It currently supports the
Oculus Touch and Microsoft Xbox controllers on desktop platforms. Gamepads compatible with Samsung Gear
VR, such as the Samsung EI-GP20 and Moga Pro, must be Android compatible and support Bluetooth 3.0. For
more details on supported mobile gamepad features, see System and Hardware Requirements in our Mobile
SDK documentation.
When used with tracked controllers such as Oculus Touch, OVRInput also provides position and orientation
data through GetLocalControllerPosition() and GetLocalControllerRotation(), which return a
Vector3 and Quaternion, respectively.
Controller poses are returned by the Constellation tracking system and are predicted simultaneously with
the headset. These poses are reported in the same coordinate frame as the headset, relative to the initial
center eye pose, and may be used for rendering hands or objects in the 3D world. They are also reset by
OVRManager.display.RecenterPose(), similar to the head and eye poses.
OVRInput provides control of haptic vibration feedback on compatible controllers. For example,
SetControllerVibration() sets vibration frequency and amplitude.
For keyboard and mouse control, we recommend using the UnityEngine.Input scripting API (see Unitys Input
scripting reference for more information).
Mobile input bindings are now automatically added to InputManager.asset if they do not already exist. The
InputManager.asset file previously provided to populate input bindings for mobile was deprecated with
Utilities 0.1.3.0, and is currently included for legacy use with our deprecated OVRGamepadController and
OVRInputControl APIs.
For more information, see the OVRInput reference. For more information on Unitys input system and Input
Manager, documented here: http://docs.unity3d.com/Manual/Input.html and http://docs.unity3d.com/
ScriptReference/Input.html.
Note: The term Touch in OVRInput refers to actual Oculus Touch controllers.

OVRInput Usage
The primary usage of OVRInput is to access controller input state through Get(), GetDown(), and GetUp().
Get() queries the current state of a control.
GetDown() queries if a control was pressed this frame.
GetUp() queries if a control was released this frame.
Control Input Enumerations
There are multiple variations of Get() that provide access to different sets of controls. These sets of controls
are exposed through enumerations defined by OVRInput as follows:

Unity|OVRInput|21

Control

Enumerates

OVRInput.Button

Traditional buttons found on gamepads and the Oculus Touch

controllers.

OVRInput.Touch

Capacitive-sensitive control surfaces found on the Oculus Touch

controllers.

OVRInput.NearTouch

Proximity-sensitive control surfaces found on the Oculus Touch

controllers.

OVRInput.Axis1D

One-dimensional controls such as triggers that report a floating

point state.

OVRInput.Axis2D

Two-dimensional controls such as thumbsticks that report a

Vector2 state.

A secondary set of enumerations mirror the first, defined as follows:

OVRInput.RawButton
OVRInput.RawTouch
OVRInput.RawNearTouch
OVRInput.RawAxis1D
OVRInput.RawAxis2D
The first set of enumerations provides a virtualized input mapping that is intended to assist developers with
creating control schemes that work across different types of controllers. The second set of enumerations
provides raw unmodified access to the underlying state of the controllers. We recommend using the first set of
enumerations, since the virtual mapping provides useful functionality, as demonstrated below.
Button, Touch, and NearTouch
In addition to traditional gamepad buttons, the Oculus Touch controllers feature capacitive-sensitive control
surfaces which detect when fingers make physical contact (a touch), as well as when they are in close
proximity (a near touch). This allows for detecting several distinct states of a users interaction with a specific
control surface. For example, if a users index finger is fully removed from a control surface, the NearTouch for
that control will report false. As the users finger approaches the control and gets within close proximity to it,
the NearTouch will report true prior to the user making physical contact. When the user makes physical contact,
the Touch for that control will report true. When the user pushes the index trigger down, the Button for that
control will report true. These distinct states can be used to accurately detect the users interaction with the
controller and enable a variety of control schemes.
More on Controls
Example Usage:
// returns true if the primary button (typically A) is currently pressed.
OVRInput.Get(OVRInput.Button.One);

22|OVRInput|Unity

// returns true if the primary button (typically A) was pressed this frame.
OVRInput.GetDown(OVRInput.Button.One);
// returns true if the X button was released this frame.
OVRInput.GetUp(OVRInput.RawButton.X);
// returns a Vector2 of the primary (typically the Left) thumbsticks current state.
// (X/Y range of -1.0f to 1.0f)
OVRInput.Get(OVRInput.Axis2D.PrimaryThumbstick);
// returns true if the primary thumbstick is currently pressed (clicked as a button)
OVRInput.Get(OVRInput.Button.PrimaryThumbstick);
// returns true if the primary thumbstick has been moved upwards more than halfway.
// (Up/Down/Left/Right - Interpret the thumbstick as a D-pad).
OVRInput.Get(OVRInput.Button.PrimaryThumbstickUp);
// returns a float of the secondary (typically the Right) index finger triggers current state.
// (range of 0.0f to 1.0f)
OVRInput.Get(OVRInput.Axis1D.SecondaryIndexTrigger);
// returns a float of the left index finger triggers current state.
// (range of 0.0f to 1.0f)
OVRInput.Get(OVRInput.RawAxis1D.LIndexTrigger);
// returns true if the left index finger trigger has been pressed more than halfway.
// (Interpret the trigger as a button).
OVRInput.Get(OVRInput.RawButton.LIndexTrigger);
// returns true if the secondary gamepad button, typically B, is currently touched by the user.
OVRInput.Get(OVRInput.Touch.Two);

In addition to specifying a control, Get() also takes an optional controller parameter. The list of supported
controllers is defined by the OVRInput.Controller enumeration (for details, see the OVRInput reference).
Specifying a controller can be used if a particular control scheme is intended only for a certain controller type.
If no controller parameter is provided to Get(), the default is to use the Active controller, which corresponds
to the controller that most recently reported user input. For example, a user may use a pair of Oculus Touch
controllers, set them down, and pick up an Xbox controller, in which case the Active controller will switch to
the Xbox controller once the user provides input with it. The current Active controller can be queried with
OVRInput.GetActiveController() and a bitmask of all the connected Controllers can be queried with
OVRInput.GetConnectedControllers().
Example Usage:
// returns true if the Xbox controllers D-pad is pressed up.
OVRInput.Get(OVRInput.Button.DpadUp, OVRInput.Controller.Gamepad);
// returns a float of the Hand Triggers current state on the Left Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.Touch);
// returns a float of the Hand Triggers current state on the Right Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.SecondaryHandTrigger, OVRInput.Controller.Touch);

Note that the Oculus Touch controllers may be specified either as the combined pair (with
OVRInput.Controller.Touch), or individually (with OVRInput.Controller.LTouch and RTouch). This
is significant because specifying LTouch or RTouch uses a different set of virtual input mappings that allow
more convenient development of hand-agnostic input code. See the virtual mapping diagrams in Touch Input
Mapping for an illustration.
Example Usage:
// returns a float of the Hand Triggers current state on the Left Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.LTouch);
// returns a float of the Hand Triggers current state on the Right Oculus Touch controller.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, OVRInput.Controller.RTouch);

Unity|OVRInput|23

This can be taken a step further to allow the same code to be used for either hand by specifying the controller
in a variable that is set externally, such as on a public variable in the Unity Editor.
Example Usage:
// public variable that can be set to LTouch or RTouch in the Unity Inspector
public Controller controller;

// returns a float of the Hand Triggers current state on the Oculus Touch controller
// specified by the controller variable.
OVRInput.Get(OVRInput.Axis1D.PrimaryHandTrigger, controller);
// returns true if the primary button (A or X) is pressed on the Oculus Touch controller
// specified by the controller variable.
OVRInput.Get(OVRInput.Button.One, controller);

This is convenient since it avoids the common pattern of if/else checks for Left/Right hand input mappings.

Touch Input Mapping

The following diagrams illustrate common input mappings for Oculus Touch controllers. For more information
on additional mappings that are available, refer to the OVRInput reference.
Virtual Mapping (Accessed as a Combined Controller)
When accessing the Touch controllers as a combined pair with OVRInput.Controller.Touch, the virtual mapping
closely matches the layout of a typical gamepad split across the Left and Right hands.

Virtual Mapping (Accessed as Individual Controllers)

When accessing the Left or Right Touch controllers individually with OVRInput.Controller.LTouch or
OVRInput.Controller.RTouch, the virtual mapping changes to allow for hand-agnostic input bindings. For
example, the same script can dynamically query the Left or Right Touch controller depending on which hand it
is attached to, and Button.One will be mapped appropriately to either the A or X button.

24|OVRInput|Unity

Raw Mapping
The raw mapping directly exposes the Touch controllers. The layout of the Touch controllers closely matches
the layout of a typical gamepad split across the Left and Right hands.

Xbox Input Handling

Virtual Mapping
This diagram shows a common implementation of Xbox controller input bindings using
OVRInput.Controller.Gamepad.

Unity|OVRInput|25

Raw Mapping
The raw mapping directly exposes the Xbox controller.

26|Configuring for Build|Unity

Configuring for Build

This section describes building your project to PC and mobile targets.

PC Build Target: Microsoft Windows and Mac OS X

This section describes targeting Unity project builds to Microsoft Windows and Mac OS X.

Build Settings and Player Settings

To build the demo as a standalone full screen application, you will need to change a few project settings to
maximize the fidelity of the demo.
Build Settings
Click on File > Build Settings... and select one of the following:
For Windows, set Target Platform to Windows and set Architecture to either x86 or x86 64.
Figure 3: Build Settings: PC

Unity|Configuring for Build|27

For Mac, set Target Platform to Mac OS X.

Figure 4: Build Settings: Mac

Note: Be sure to add any scenes you wish to include in your build to Scenes In Build..

28|Configuring for Build|Unity

Player Settings
Within the Build Settings pop-up, click Player Settings. In the Other Settings frame, select Virtual Reality
Supported. All additional required settings are enforced automatically.
Figure 5: Player Settings

In the Build Settings pop-up, select Build. If prompted, specify a name and location for the build.
If you are building in the same OS, the demo should start to run in full screen mode as a standalone
application.

Quality Settings
You may notice that the graphical fidelity is not as high as the pre-built demo. You will need to change some
additional project settings to get a better looking scene.

Unity|Configuring for Build|29

Navigate to Edit > Project Settings > Quality. Set the values in this menu to the following:
Figure 6: Quality settings for Oculus demo

The most important value to modify is Anti-aliasing. The anti-aliasing must be increased to compensate for the
stereo rendering, which reduces the effective horizontal resolution by 50%. An anti-aliasing value of 2X is ideal 4x may be used if you have performance to spare, and 8x usually isn't worth it.
Now rebuild the project again, and the quality should be at the same level as the pre-built demo.

Running the Build

Now that the project is properly configured for VR, its time to install and run the application.
PC builds create a single executable file that may be used in either Direct Display or Extended Display modes.

Mobile Build Target: Android

This section describes targeting Unity project builds to Android.
Android Manifest
The manifests of projects built with Unity's first-party VR support enabled are automatically updated during
build to meet our requirements (landscape orientation, vr_only, et cetera). All other values, such as Entitlement
Check settings, will not be modified. Do not add the noHistory attribute to your manifest.
Do not add the noHistory attribute to your manifest.

30|Configuring for Build|Unity

Build Settings
From the File menu, select Build Settings. From the Build Settings menu, select Android as the
platform. Set Texture Compression to ASTC.

Player Settings
1. Click the Player Settings button and select the Android tab. In the Other Settings frame, select
Virtual Reality Supported. All required settings are enforced automatically, but you may wish to make

Unity|Configuring for Build|31

additional settings as appropriate, such as enabling Multithreaded Rendering and setting Graphics APIs to
OpenGLES3.
Figure 7: Player Settings

2. Select the Splash Image section. For Mobile Splash image, choose a solid black texture.
Note: Custom Splash Screen support is not available with Unity Personal edition.

Running the Build

Now that the project is properly configured for VR, its time to install and run the application on the Android
device.
Applications written for development are not launched through the Oculus Home menu system. Instead,
you build the application directly to your phone, and will be instructed to insert your phone into the Gear VR
headset to launch the application automatically.
To run the application in the future, remove your phone from the Gear VR headset, launch the application
directly on the phone, and insert the phone into the Gear VR when instructed to do so.
1. Copy an Oculus Signature File specific to your mobile device to the folder <project>/Assets/Plugins/
Android/assets/ or the application will not run. If this folder does not exist, go ahead and create it. See
"Create Your Signature Files" in the Oculus Mobile Submission Guidelines for more information.
2. Be sure the project settings from the steps above are saved with File > Save Project.
3. If you are not already connected to your phone via USB, connect now. Unlock the phone lock screen.
4. From the File menu, select Build Settings. While in the Build Settings menu, add the Main.scene to Scenes
in Build. Next, verify that Android is selected as your Target Platform and select Build and Run. If asked,
specify a name and location for the .apk.
The .apk will be installed and launched on your Android device.

32|Best Practices: Mobile|Unity

Best Practices: Mobile

This section provides simple guidelines to help your Android Unity app perform well.
Good performance is critical for all VR applications, but the limitations inherent to mobile development warrant
special consideration.
Please review Performance Advice for Early Titles in Design Guidelines and Mobile VR Design and
Performance Guidelines before reading this documentation - they may be found in the Mobile SDK
documentation.

Design Considerations
Please review Design Guidelines in the Mobile SDK documentation if you have not already done so.
Start up Sequence
For good VR experiences, all graphics should be rendered such that the user is always viewing a proper threedimensional stereoscopic image. Additionally, head-tracking must be maintained at all times.
An example of how to do this during application start up is demonstrated in the SDKExamples Startup_Sample
scene:

Solid black splash image is shown for the minimum time possible.
A small test scene with 3D logo and 3D rotating widget or progress meter is immediately loaded.
While the small start up scene is active, the main scene is loaded in the background.
Once the main scene is fully loaded, the start scene transitions to the main scene using a fade.

Universal Menu Handling

Applications will need to handle the Back Key long-press action which launches the Universal Menu as well
as the Back Key short-press action which launches the Confirm-Quit to Home Menu which exits the current
application and returns to the Oculus Home application.
An example of demonstrating this functionality is in the SDKExamples GlobalMenu_Sample scene.
More information about application menu options and access can be found in Universal Menu in the Mobile
SDK documentation.

Best Practices

Be Batch Friendly. Share materials and use a texture atlas when possible.
Prefer lightmapped, static geometry.
Prefer lightprobes instead of dynamic lighting for characters and moving objects.
Bake as much detail into the textures as possible. E.g., specular reflections, ambient occlusion.
Only render one view per eye. No shadow buffers, reflections, multi-camera setups, et cetera.
Keep the number of rendering passes to a minimum. No dynamic lighting, no post effects, don't resolve
buffers, dont use grabpass in a shader, et cetera.

Unity|Best Practices: Mobile|33

Avoid alpha tested / pixel discard transparency. Alpha-testing incurs a high performance overhead.
Replace with alpha-blended if possible.
Keep alpha blended transparency to a minimum.
Use Texture Compression. Favor ASTC.
Check the Disable Depth and Stencil* checkbox in the Resolution and Presentation pane in Player Settings.

General CPU Optimizations

To create a VR application or game that performs well, careful consideration must be given to how features
are implemented. Scene should always run at 60 FPS, and you should avoid any hitching or laggy performance
during any point that the player is in your game.

Be mindful of the total number of GameObjects and components your scenes use.
Model your game data and objects efficiently. You will generally have plenty of memory.
Minimize the number of objects that actually perform calculations in Update() or FixedUpdate().
Reduce or eliminate physics simulations when they are not actually needed.
Use object pools to respawn frequently-used effects or objects instead of allocating new ones at runtime.
Use pooled AudioSources versus PlayOneShot sounds, as the latter allocate a GameObject and destroy it
when the sound is done playing.
Avoid expensive mathematical operations whenever possible.
Cache frequently-used components and transforms to avoid lookups each frame.
Use the Unity Profiler to:
Identify expensive code and optimize as needed.
Identify and eliminate Garbage Collection allocations that occur each frame.
Identify and eliminate any spikes in performance during normal play.
Do not use Unitys OnGUI() calls.
Do not enable gyro or the accelerometer. In current versions of Unity, these features trigger calls to
expensive display calls.
All best practices for mobile app and game development generally apply.
Note: The Unity Profiler is not available for Unity Free.

Rendering Optimization
While building your app, the most important thing to keep in mind is to be conservative on performance from
the start.

Keep draw calls down.

Be mindful of texture usage and bandwidth.
Keep geometric complexity to a minimum.
Be mindful of fillrate.

34|Best Practices: Mobile|Unity

Reducing Draw Calls

Keep the total number of draw calls to a minimum. A conservative target would be less than 100 draw calls per
frame.
Unity provides several built-in features to help reduce draw calls such as batching and culling.
Draw Call Batching
Unity attempts to combine objects at runtime and draw them in a single draw call. This helps reduce overhead
on the CPU. There are two types of draw call batching: Static and Dynamic.
Static batching is used for objects that will not move, rotate or scale, and must be set explicitly per object. To
mark an object static, select the Static checkbox in the object Inspector.

Dynamic batching is used for moving objects and is applied automatically when objects meet certain criteria,
such as sharing the same material, not using real-time shadows, or not using multipass shaders. More
information on dynamic batching criteria may be found here: https://docs.unity3d.com/Documentation/Manual/
DrawCallBatching.html
Culling
Unity offers the ability to set manual per-layer culling distances on the camera via Per-Layer Cull Distance.
This may be useful for culling small objects that do not contribute to the scene when viewed from a given
distance. More information about how to set up culling distances may be found here: https://docs.unity3d.com/
Documentation/ScriptReference/Camera-layerCullDistances.html.
Unity also has an integrated Occlusion Culling system. The advice to early VR titles is to favor modest scenes
instead of open worlds, and Occlusion Culling may be overkill for modest scenes. More information about
the Occlusion Culling system can be found here: http://blogs.unity3d.com/2013/12/02/occlusion-culling-inunity-4-3-the-basics/.
Reducing Memory Bandwidth
Texture Compression: Texture compression offers a significant performance benefit. Favor ASTC
compressed texture formats.
Texture Mipmaps: Always use mipmaps for in-game textures. Fortunately, Unity automatically generates
mipmaps for textures on import. To see the available mipmapping options, switch Texture Type to
Advanced in the texture inspector.
Texture Filtering: Trilinear filtering is often a good idea for VR. It does have a performance cost, but it is
worth it. Anisotropic filtering may be used as well, but keep it to a single anisotropic texture lookup per
fragment.
Texture Sizes: Favor texture detail over geometric detail, e.g., use high-resolution textures over more
triangles. We have a lot of texture memory, and it is pretty much free from a performance standpoint. That
said, textures from the Asset Store often come at resolutions which are wasteful for mobile. You can often
reduce the size of these textures with no appreciable difference.
Framebuffer Format: Most scenes should be built to work with a 16 bit depth buffer resolution.
Additionally, if your world is mostly pre-lit to compressed textures, a 16 bit color buffer may be used.
Screen Resolution: Setting Screen.Resolution to a lower resolution may provide a sizeable speedup for
most Unity apps.

Unity|Best Practices: Mobile|35

Reduce Geometric Complexity

Keep geometric complexity to a minimum. 50,000 static triangles per-eye per-view is a conservative target.
Verify model vert counts are mobile-friendly. Typically, assets from the Asset Store are high-fidelity and will
need tuning for mobile.
Unity Pro provides a built-in Level of Detail System (not available in Unity Free), allowing lower-resolution
meshes to be displayed when an object is viewed from a certain distance. For more information on how
to set up a LODGroup for a model, see the following: https://docs.unity3d.com/Documentation/Manual/
LevelOfDetail.html
Verify your vertex shaders are mobile friendly. And, when using built-in shaders, favor the Mobile or Unlit
version of the shader.
Bake as much detail into the textures as possible to reduce the computation per vertex: https://
docs.unity3d.com/430/Documentation/Manual/iphone-PracticalRenderingOptimizations.html
Be mindful of GameObject counts when constructing your scenes. The more GameObjects and Renderers in
the scene, the more memory consumed and the longer it will take Unity to cull and render your scene.
Reduce Pixel Complexity and Overdraw
Pixel Complexity: Reduce per-pixel calculations by baking as much detail into the textures as possible. For
example, bake specular highlights into the texture to avoid having to compute the highlight in the fragment
shader.
Verify your fragment shaders are mobile friendly. And, when using built-in shaders, favor the Mobile or Unlit
version of the shader.
Overdraw: Objects in the Unity opaque queue are rendered in front to back order using depth-testing to
minimize overdraw. However, objects in the transparent queue are rendered in a back to front order without
depth testing and are subject to overdraw.
Avoid overlapping alpha-blended geometry (e.g., dense particle effects) and full-screen post processing
effects.

Unity Profiling Tools

Even following the guidelines above, you may find you are not hitting a solid 60 FPS. The next section details
the various tools provided by Unity to help you diagnose bottlenecks in Android applications. For additional
profiling tools, see "Performance Analysis" in the Mobile SDK documentation.
Unity Profiler
Unity comes with a built-in profiler. The profiler provides per-frame performance metrics, which can be used to
help identify bottlenecks.
You may profile your application as it is running on your Android device using adb or WIFI. For steps on
how to set up remote profiling for your device, please refer to the Android section of the following Unity
documentation: https://docs.unity3d.com/Documentation/Manual/Profiler.html.

36|Best Practices: Mobile|Unity

The Unity Profiler displays CPU utilization for the following categories: Rendering, Scripts, Physics,
GarbageCollector, and Vsync. It also provides detailed information regarding Rendering Statistics, Memory
Usage (including a breakdown of per-object type memory usage), Audio and Physics Simulation statistics.
GPU Usage data for Android is not available at this time.
The Unity profiler only displays performance metrics for your application. If your app isnt performing as
expected, you may need to gather information on what the entire system is doing. Show Rendering Statistics
Unity provides an option to display real-time rendering statistics, such as FPS, Draw Calls, Tri and Vert Counts,
VRAM usage.
While in the Game View, pressing the Stats button (circled in red in the upper-right of the following screenshot)
above the view window will display an overlay showing real-time render statistics.

Show GPU Overdraw

Unity provides a specific render mode for viewing overdraw in a scene. From the Scene View Control Bar, select
OverDraw in the drop-down Render Mode selection box.
In this mode, translucent colors will accumulate providing an overdraw heat map where more saturated
colors represent areas with the most overdraw.

Unity|Best Practices: Mobile|37

38|Troubleshooting and Known Issues|Unity

Troubleshooting and Known Issues

This section outlines some currently known issues with the Oculus Unity Integration and the Oculus Utilities for
Unity.

General Issues
When switching between a mobile application and System Activities screen, the back button becomes
stuck in the "down" state. [Unity 5 with Mobile SDK 0.6.0.1, 0.6.1.0, 0.6.2.0]
A current workaround is to send an artificial back-button-up event on resume. If the user wants to go
immediately back to the System Activities from the app, they will need to press and hold the back button
longer than 0.75 seconds.
No VR support for Editor Game View [Legacy Integration packages with Unity versions prior to 4.6.7p4]
Fixed in Unity 4.6.8.
Slight increase in rendering latency for trivial scenes. [Legacy Integration 0.6.0.2, fixed since Integration
0.6.2]
Simple scenes (e.g., scenes that take < 3 ms to render) may show 2-3 ms higher latency with Integration 0.6.0.2.
Typical scenes take > 5 ms to render and should be unaffected.
D3D log errors about texture; random textures appear frozen full-screen instead of the eye buffer [Unity
5.0 - 5.1.1p2]
Linear lighting and MSAA are broken with VR. [Unity 5.1.2p3-5.1.3p1]
Mac will not vsync properly for now. [Utilities 0.1.0.0]
Unity Editor crashes in Game View when VR is enabled. [Unity 5.1.2p2]
This is a known issue. See Compatibility and Requirements for recommended Unity versions.
Unity 5 hangs while importing assets from SDKExamples [SDKExamples 0.1.0 Beta].
Unity 5 is known to import ETC2-compressed assets very slowly.

PC
Legacy Integration 0.6.0.1 and earlier are not compatible with Oculus Runtime for Windows 0.7.
The app does not launch as a VR app.
Verify that you are using a compatible runtime - see Compatibility and Requirements for more details.
Ensure you have administrator rights to the system where you are installing the integration. Verify that the HMD
is plugged in and working normally, and that you have installed the Oculus runtime. Also verify that you have
not selected D3D 9 or Windows GL as the renderer (Legacy Integration only).
Rift apps run in a window and are mirrored to the Rift in Direct Display mode. [Integration 0.6.0.0,
Integration 0.6.0.1, Utilities 0.1.0.0 Beta]

Unity|Troubleshooting and Known Issues|39

You can disable this behavior by turning off OVRManager.mirrorToMainWindow.

Display settings forced to 1920x1080; Unity startup splash suppressed. [Integration 0.6.0.0, Integration
0.6.0.1. Fixed as of Legacy Integration 0.6.0.2.]
To enable Rift support, the internal OVRShimLoader script forces your builds to 1920x1080 full-screen
resolution and suppresses Unity's startup splash screen by default. You can still access it and change the
settings when running your executable (<AppName.exe>.exe) by holding the ALT key immediately after
launch. To disable this behavior, navigate to Edit Preferences... > Oculus VR and uncheck the Optimize Builds
for Rift box.
The Rift displays a black screen while using Unity Editor. [Integration 0.6.0.0, Integration 0.6.0.1]
Use Extended Display mode instead of Direct Display mode. See "Direct Mode Display Driver" in Preparing for
Development: PC SDK for more information.

OS X
Mac Tearing [All first-party Unity VR in 5.1.0-5.1.2 using Utilities 0.1.0)]
Editor preview and standalone players do not vsync properly, resulting in a vertical tear and/or judder on DK2.
Android players are unaffected, even if built on a Mac.
Unity Editor crashes when building APK or pressing play in Play View; Mac standalone player crashes.
[Unity 4 with Oculus Runtime for OS X 0.4.4 and Legacy Integration 0.6.0.2 or 0.6.1]
Fixed in Legacy Integration 0.6.2.0. In older versions, update to Oculus Runtime for OS X 0.5.0.1. Before
updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous
installation.

Mobile
Audio corruption with Android low-latency audio path. [Unity 4.6.1p4 - 4.6.7p2; 5.1.0f2 and up. Fixed
Unity 4.6.7p3 and up.]
This sporadic issue affects some developers using Unity versions built on Androids low-latency audio path
handling. Symptoms include sampling problems resulting in hitching and garbled playback speeds that do not
affect pitch.
This issue has been fixed in Unity 5.2.0b4 and up. Unity is aware of the issue and is working on a fix for all
versions.
Game scene is missing or just renders the background color when pressing Play in Unity. [Integration
0.6.0.0, Integration 0.6.0.1]
Check the [Project Path]/Assets/Plugins/ folder and make sure that the Oculus plugins have not moved. See the
Unity console for additional information.
Issues with updating to the latest Oculus Unity Integration with Team Licensing and Perforce Integration
enabled. [Integration 0.6.0.0, Integration 0.6.0.1]
If you have Team Licensing and Perforce Integration enabled, you may need to check out the OVR and Plugins
folders manually before importing the updated Unity package.
The app does not launch as a VR app.

40|Troubleshooting and Known Issues|Unity

Verify that you have selected Virtual Reality Enabled in Player Settings.

Contact Information
Questions?
Visit our developer support forums at https://developer.oculus.com
Our Support Center can be accessed at https://support.oculus.com.

Unity|Tutorial: Build a Simple VR Unity Game|41

Tutorial: Build a Simple VR Unity Game

This tutorial describes the steps necessary to build, load, and run a simple Unity 3D application on the Oculus
Rift or Samsung Gear VR.
It is intended to serve as a basic introduction for developers who are new to VR development and to Unity.
Once the necessary tools are set up, this process should take a few hours to complete. By the end, you will
have a working mobile application that you can play and demonstrate on your Oculus Rift or Gear VR device, to
the amazement of your friends and loved ones.
We will build and modify the Unity game Roll-a-ball to add VR capability. The game is controllable by keyboard
or by the Samsung EI-GP20 gamepad.
Requirements

Oculus DK2 (Desktop) or Gear VR with compatible Samsung phone (Mobile)

Samsung EI-GP20 gamepad (required for Mobile; optional for Desktop)
PC running Windows 7/8 or a Mac running OS X 10
Unity 5 (see Compatibility and Requirements for specific )

You will also need to refer to the relevant Oculus SDK documentation, available for download here: https://
developer.oculus.com/documentation/

Installation and Preparation

1. Install the appropriate Oculus SDK and prepare for development.
Desktop: Download and install the Oculus PC SDK and Utilities package from Oculus PC SDK Downloads.
Prepare for development as described in the Oculus Rift Getting Started Guide. By the time you have
completed this process, you should be able to run the Demo Scene as described in that guide.
Mobile: Download and install the Oculus Mobile SDK from Oculus Mobile SDK Downloads. Prepare for
development as described by the Mobile SDK Setup Guide. By the time you have completed this process,
you should be able to communicate with your Samsung phone via USB. To verify this, retrieve the device
ID from your phone by connecting via USB and sending the command adb devices from a command
prompt. If you are communicating successfully, the phone will return its device ID. You may wish to make a
note of it - you will need it later to request a Oculus Signature File (see step four in Modify Roll-a-ball for VR
for more information).
2. Install Unity.
Download and install Unity Personal or Professional v 5.1.0p2 or later here: http://docs.unity3d.com/Manual/
index.html. Unity provides extensive documentation to introduce users to the environment. You may wish
to begin by reviewing their documentation to gain a basic familiarity with core concepts such as the Editor,
GameObjects, prefabs, projects, and scenes.
3. Build the Unity Roll-a-ball application.
Unity provides a number of video tutorials that walk you through the process of creating a simple game. The
first in the series provides instructions for creating the Roll-a-ball application, in which you use the keyboard
or gamepad to control a ball that rolls around a game board and picks up floating token counters:http://
unity3d.com/learn/tutorials/projects/roll-a-ball
The development process is covered in eight short video tutorials which run from around five to fifteen
minutes in length. Allow for a few hours to complete the procedure.

42|Tutorial: Build a Simple VR Unity Game|Unity

The final video in the series, "107. Publishing the game," describes building the Roll-a-ball game for play
in a web browser. You may skip this lesson if you wish for the purposes of this exercise, as we will follow a
different procedure for building a playable application (PC/Mac) or APK (Android).
Note: We refer to the assets, folders, and so forth by the names used in the Unity tutorial, so it is
helpful to follow the names they use in their example.
4. Duplicate your Roll-a-ball project (optional).
Once you have completed building Roll-a-ball, you may wish to create a duplicate Roll-a-ball project
specifically for VR development. It can be useful to retain a backup of the original unmodified Roll-a-ball
project in case you make mistakes or wish to work with it later without the VR assets.
To duplicate the Roll-a-ball project, simply navigate in your OS to the Unity project folder containing your
Roll-a-ball project, copy the folder and all of its contents, and rename it. For this tutorial, we will use the
project folder name Roll-a-ball-VR.
5. Launch the new project and prepare the game scene.
1. Launch Unity and select File > Open Project... and select the project folder location for Roll-a-ball-VR in
order to launch the project.
2. In your Project tab, open Assets > _Scenes and select "MiniGame."
3. Press F2 and rename the scene "VRMiniGame."
4. Open the scene "VRMiniGame."

Modify Roll-a-ball for VR

1. Elevate camera above the game board.
Select Main Camera in the Hierarchy view and set the Position fields of the Main Camera Transform in the
Unity Inspector to the following values: X = 0; Y = 10; Z = -15.
2. Rotate camera forward for a better view.
Set the Rotation field of the OVRCameraRig Transform to the following value: X = 35; Y = 0; Z = 0.

Unity|Tutorial: Build a Simple VR Unity Game|43

Enter Play mode by pressing the play button. The Unity Game View preview will show the image
corresponding to the left eye buffer. If you are using the PC SDK, you will see the Health and Safety
Warning appear over the game; press any key to continue past it.
Figure 8: Roll-a-ball VR in Unity Scene and Game Views

3. Speed up the ball.

With its current configuration, the ball will travel slowly when controlled by the Samsung gamepad. Select
Player in the Hierarchy view and change the Speed value in the Player Controller (Script) tab of the Inspector
view from 500 to 800.
4. Save your scene and project before building your application.
5. Enable Virtual Reality Supported in Player Settings.
Go to Edit > Project Settings > Player and select PC or Android as appropriate. In the Other Settings pane,
check the Virtual Reality Supported checkbox.
6. Sign your application (Mobile Only).
To access your Samsung phone's VR capabilities, you will need to sign your application with an Oculus
Signature File (osig). If you recorded your device ID earlier, you may use it now to request your osig file.
Note that you need only one osig per mobile device.
You may obtain an osig from our self-service portal here: https://developer.oculus.com/tools/osig/. Once
you have received an osig, copy it to your Unity project folder in /Roll-a-ball-VR/Assets/Plugins/Android/
assets/.
More information may be found on application signing in "Creating Your Signature File" in the Mobile App
Preparation and Submission Guidelines.

44|Tutorial: Build a Simple VR Unity Game|Unity

Build and Play

Build and Launch
If you are developing for desktop, you will build an executable file that you may launch with your PC or Mac. If
you are developing for mobile, you will build an APK and load it onto your phone, and then insert the phone
into the Gear VR to launch your game. Follow the build instructions as described by the section Configuring for
Build section, which contains important details for enabling VR for your project.
Play
Go ahead and try it out! You may use your keyboard or a paired Samsung gamepad to control your ball and
collect the game pickup objects.
Note: Because the GUIText display we built in the Roll-a-ball tutorial will not work with OVRCameraRig
without substantial modification, you will not see the score counter or "You win!" message when all the
pieces have been collected.
Launching the Game on Gear VR
If you select Apps from the Samsung home screen, you will see Roll-a-ball-VR listed with the other apps. You
may launch the application directly, and when instructed, put the phone in the Gear VR. It will not be visible
from Oculus Home.

Unity|Unity-SDK Version Compatibility|45

Unity-SDK Version Compatibility

This reference describes the relationship between Unity versions, Oculus PC and Mobile SDKs, and Oculus
Unity Integration and Utilities packages.
Utilities for Unity 5x Versions
Release Date

Integration

PC SDK

Mobile SDK

Unity

11/16/2015

0.1.3.0 Beta

0.8.0.0

1.0.0

5.3.1p4

10/30/2015

0.1.3.0 Beta

0.8.0.0

0.6.2.0

5.2.2p2

10/1/2015

0.1.2.0 Beta

0.7.0.0

0.6.2.0

5.2.1p2

7/6/2015

0.1.0.0 Beta

0.6.0.1

0.5.0

5.1.1

Unity 4x Integration Versions

Release Date

Integration

PC SDK

Mobile SDK

Unity

10/30/2015

0.8.0.0

0.8.0.0

1.0.0

4.7.0f1

9/08/2015

0.6.2.0

0.7.0.0

0.6.2.0

4.6.7+

8/14/2015

0.6.1.0

0.6.0.1

0.6.1.0

4.6.7+

8/7/2015

0.6.0.2

0.6.0.1

0.6.0.1

4.6.7

6/25/2015

D 0.6.0.1

0.5.0.1

0.6.0.1

4.6

6/12/2015

M 0.6.0.1

0.5.0.1

0.6.0.1

4.6

5/15/2015

D 0.6.0.0

0.5.0.1

0.5.0

4.6

3/31/2015

M 0.5.0

0.5.0.1

0.5.0

4.6

3/26/2015

D 0.5.0.1

0.5.0.1

0.5.0

4.6

3/20/2015

M 0.4.3.1

0.4.4

0.4.3.1

4.5

2/27/2015

M 0.4.3

0.4.4

0.4.3

4.5

1/23/2015

M 0.4.2

0.3.2

0.4.2

4.5

1/7/2015

M 0.4.1

0.3.2

0.4.1

4.4

12/4/2014

D 0.4.4

0.4.4

0.4.0

4.6

11/12/2014

M 0.4.0

0.3.2

0.4.0

4.4

11/10/2014

D 0.4.3.1

0.4.3.1

N/A

4.5

10/24/2014

D 0.4.3

0.4.3

N/A

4.5

9/4/2014

D 0.4.2

0.4.2

N/A

4.5

8/11/2014

D 0.4.1

0.4.1

N/A

4.4

7/24/2014

D 0.4.0

0.4.0

N/A

4.4

5/22/2014

D 0.3.2

0.3.2

N/A

4.3

4/14/2014

D 0.3.1

0.3.1

N/A

4.3

10/10/2013

D 0.2.5

0.2.5

N/A

4.3

46|Release Notes|Unity

Release Notes
This section describes changes for each version release.

0.1 Beta Utilities for Unity Release Notes

This document provides an overview of new features, improvements, and fixes included in the latest version of
the Oculus Utilities for Unity.
Utilities for Unity 0.1.3.0 Beta
Overview of Major Changes
Note: For detailed information about Unity version compatibility, please see Compatibility and
Requirements.
This document provides an overview of new features, improvements, and fixes included in the latest version of
the Utilities for Unity 5.x. For information on first-party changes to Unity VR support for Oculus, see the Unity
Release Notes for the appropriate version.
Utilities for Unity 0.1.3 extends OVRInput support to mobile. OVRInputControl and OVRGamepadController are
now deprecated and will be removed in a future release.
Mobile input bindings are now automatically added to InputManager.asset if they do not already exist - it is
no longer required to replace InputManager.asset with Oculus version. However, this asset is still provided for
now to maintain legacy support for the deprecated OVRGamepadController and OVRInputControl scripts.
New Features
Default mobile input bindings are now programmatically generated when projects are imported if they do
not already exist.
Replacing InputManager.asset is no longer required to enable gamepad support on mobile.
API Changes
Added mobile support OVRInput.
Deprecated OVRInputControl and OVRGamepadController.
Bug Fixes
Fixed mobile gamepad thumbstick deadzone/drift handling and axis scaling.
Fixed mobile gamepad support when multiple gamepads are paired.
Fixed mobile gamepad bindings for triggers, D-pad, thumbstick presses, etc.
Utilities for Unity 0.1.2.0 Beta
Overview of Major Changes
This version adds an alpha preview release of OVRInput, which provides a unified input API for accessing
Oculus Touch and Microsoft Xbox controllers.

Unity|Release Notes|47

New Features

Redesigned input API for Oculus Touch controllers and Xbox gamepads.
Added h264 hardware-decoder plugin for Gear VR.
Added face-locked layer support to OVROverlay when parented to the camera.
Reduced latency in the pose used by the main thread for raycasting, etc.
Updated to PC SDK 0.7 and Mobile SDK 0.6.2.0.
Enabled VRSettings.renderScale on Gear VR.
Several minor performance optimizations.

SDKExamples
Restored MoviePlayerSample
API Changes
The Utilities package now requires Unity 5.1 or higher.
Added OVRInput API alpha. Refer to documentation for usage.
Exposed LeftHand/RightHand anchors for tracked controllers in OVRCameraRig.
Bug Fixes

Restored ability to toggle settings such as monoscopic rendering and position tracking.
HSWDismissed event is now correctly raised when the HSW is dismissed.
Fixed handedness of reported velocity and acceleration values.
OVRPlayerController now moves at a consistent speed regardless of scale.

Known Issues
Tearing in OS X: Editor preview and standalone players do not vsync properly, resulting in a vertical tear
and/or judder on DK2.
When switching between a mobile application and System Activities screen, the back button becomes stuck
in the "down" state. For more information and workarounds, please see Troubleshooting and Known Issues.
Utilities for Unity 0.1.0.0 Beta
Overview
This is the initial release of Oculus Utilities for Unity, for use with Unity versions 5.1.2 and later. The Utilities
extend Unity's built-in virtual reality support with the following features:

Standard camera rig with head-tracked "anchors".

Detailed tracking information such as head acceleration, velocity, and latency and the IR sensor pose.
Control over the tracking method (positional, head model only, rotation-only).
Information about the current user's IPD, eye relief, and eye height.
Control over graphics performance/quality features such as monoscopic rendering, queue-ahead (PC-only),
and chromatic aberration.
Experimental overlay support for high-quality text and video on a world-space quad.
First-person shooter-style locomotion.
Screen dimming on scene transitions.
Notification when out of positional tracking range.
Cross-platform gamepad support.

48|Release Notes|Unity

Debug overlay with real-time performance and latency graphs.

(Android only) Access to the Oculus platform UI.
(Android only) Performance and power management.
The Oculus Utilities for Unity expose largely the same API as the Oculus Unity Integration, but they offer all the
benefits of Unity's built-in VR support:
Improved rendering efficiency with less redundant work performed for each eye.
Seamless integration with the Unity Editor, including in-Editor preview and direct mode support.
Improved stability and tighter integration with features like anti-aliasing and shadows.
Non-distorted monoscopic preview on the main monitor.
Oculus SDK 0.6.0.1 support (PC and mobile).
API Changes in 0.1.0 Beta
The following Unity API changes were made:

Unity 5.1.1p3 or higher is now required.

Some script functionality was replaced by UnityEngine.VR.
Added Crescent Bay support.
Removed Linux support, for now.
Removed OvrCapi, the low-level C# wrapper for LibOVR.
Removed Gear VR MediaSurface functionality. Use Mobile Movie Texture or similar.
The integration now uses a single stereo camera instead of two separate cameras for the left and right eyes.
Direct mode now works in the Editor.
To use VR, you must enable PlayerSettings -> Virtual Reality Supported.
DirectToRift.exe no longer applies.
Editor preview is now monoscopic and does not include lens correction.
The experimental overlay quad script OVROverlay also works on the PC.

Known Issues
Pitch, roll, and translation are off for the tracking reference frame in Unity 5.1.1, especially in apps with
multiple scenes.
Mac OS X tearing. VSync is currently broken on the Mac, but works when you build for Gear VR.
Performance loss. CPU utilization may be slightly higher than in previous versions of Unity.
OVRPlayerController might end up in an unexpected rotation after OVRDisplay.RecenterPose() is called. To
fix it, call RecenterPose() again.

0.6 Unity Legacy Integration Release Notes

This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration version 0.6.
Unity 4.x Legacy Integration 0.6.2.0
Overview of Major Changes
0.6.2.0 pulls in the 0.7.0 Desktop plugins.

Unity|Release Notes|49

The source for the Unity SDKExample MediaSurface Plugin is now provided. The Media Surface Plugin provides
a native library which is used with the Android MediaPlayer for hardware decoding of a single video to a
texture. Note that the SDKExample MediaSurface Plugin is not intended to be production quality, and is
provided for reference purposes. We have made the source available in case you would like to modify it for
your use. The source and build files are located at the following SDK path: VrAppSupport/MediaSurfacePlugin.
This version adds an alpha release of OVRInput, which provides a unified input API for accessing Oculus Touch
and Microsoft Xbox controllers.
New Features
Added alpha OVRInput script to expose API for Oculus Touch and XInput-based controllers.
Now dynamically loads OpenGL ES symbols instead of hard-linking to libGLESv3.so. (Mobile)
API Changes
Now requires the new Android Plugin Java library OculusUtilities.jar (found in Assets/Plugins/Android).
Bug Fixes
Fixed Editor error message in Unity Free due to unsigned OVRPlugin.dll.
Fixed thread affinity failing to be set for the TimeWarp and DeviceManager threads. (Mobile)
Fixed device reset when repeatedly plugging and unplugging the Travel Adapter on the Galaxy SAMSUNG
S6. (Mobile)
Fixed app crash occurring when using Oculus Runtime for OS X earlier than 0.5.0.1.
Unity 4.x Legacy Integration 0.6.1.0
Overview of Major Changes
Legacy Integration 0.6.1.0 expands upon the changes in Unity 4.x PC Integration 0.6.0.2. It is fully compatible
with both our Mobile and PC SDKs.
For more information on important changes and updates relevant to this version, see the Release Notes for
Integration 0.6.0.2 below.
PC Developers
This release of the Unity Legacy Integration is compatible with the Oculus Runtime 0.6 and 0.7. All Unity
projects built with Unity 4 must update to this release, or they will not work on PCs using Runtime 0.7.
OS X Developers
Mac developers using Legacy Integration 0.6.1.0 must update to the Oculus Runtime for OS X 0.5.0.1. Before
updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous
installation.
Mobile Developers
The MediaSurface functionality has been split from the main Unity Integration and provided as a separate
plugin, libOculusMediaSurface.so included with the Unity integration package.
New Features
SDKExamples
MoviePlayer_Sample now looks for media files in the folder Streaming Assets instead of following a hardcoded path on the internal sdcard (default mp4 provided).

50|Release Notes|Unity

MoviePlayer_Sample defaults to using Unity MovieTexture functionality on the PC (media file expected as
Ogg Theora).
API Changes
No longer required to issue ResetVrModeParms to dynamically adjust CPU and GPU clock levels.
Bug Fixes
Added back one frame of latency to Unity apps to avoid object motion judder by giving Unity apps one
frame of additional GPU time (0.5.1 performance parity).
Unity 4.x PC Integration 0.6.0.2
Overview of Major Changes
Note: This release is intended for PC development only. Mobile developers should wait for Legacy
Integration version 0.6.1.0, which will ship very soon.
This release of the Unity Legacy Integration is compatible with the Oculus Runtime 0.6 and 0.7. All Unity
projects built with Unity 4 must update to this release, or they will not work on PCs using Runtime 0.7.
In most cases, migrating to this version of the legacy integration will be easy - simply open your project in
Unity, import the custom Integration unityPackage, and rebuild.
If you have previously used our C API wrappers in OvrCapi.cs, note that they have been removed and you will
need to write your own native plugins or replacement wrappers to access functionality from LibOVRRT. This
change is also required to use CAPI with our Unity 5 Utilities, so writing your own plugins or wrappers now will
help prepare for your migration to Unity 5.
A single executable file is now produced for PC builds, which will work in both Extended and Direct Display
modes.
This version removes support for D3D 9 and Windows GL.
Mac developers using Legacy Integration 0.6.0.2 must update to the Oculus Runtime for OS X 0.5.0.1. Before
updating your runtime, be sure to run uninstall.app (found in /Applications/Oculus/) to remove your previous
installation.
New Features
Compatible with Oculus Runtime versions 0.6 and 0.7.
PC builds now produce a single executable file for use in both Extended and Direct Display modes.
Oculus runtime log messages now visible in the Unity console.
Unity Editor Game View displays undistorted monoscopic preview.
No longer necessary to rotate Mac monitor for DK2 in System Preferences->Displays.
API Changes
Removed all C API wrappers from OvrCapi.cs.
Removed D3D9, Windows GL, and Linux support.
Bug Fixes
Fixed C# script problem that caused D3D11 Exclusive Mode errors.
Fixed several Editor Game View issues:

Unity|Release Notes|51

Now works for all aspect ratio settings.

Fixed bug that blacked out Game Views when more than one were created.
Fixed Game View positioning bug.
Known Issues
Mac tearing: Editor Game View and standalone players do not vsync properly, resulting in a vertical tear
and/or judder on DK2. Android players are unaffected, even if built on a Mac.
No VR support for in-editor preview on Windows until Unity 4.6.7p4.
Slight increase in latency for trivial scenes (i.e., scenes that take < 3 ms to render).
Mobile Unity Integration 0.6.0.1
New Features
Allow Unity MediaSurface dimensions to be modified via plugin interface.
Bug Fixes
Fixed not being able to enable chromatic aberration correction in the Unity plugin.
Fixed adjusting clock levels from Unity during load.
Mobile Unity Integration 0.6.0
Overview of Major Changes
Oculus Runtime is no longer required for mobile development.
Synced with the Oculus PC SDK 0.6.0.0 beta.
Allows clients to re-map plugin event IDs.
For both the PC and Mobile SDKs we recommend the following Unity versions or higher: Unity Pro 4.6.3, Unity
Professional 5.0.2.p2, Unity Free 4.6, or Unity Personal 5.0.2.p2. For mobile development, compatibility issues
are known to exist with Unity 5 and OpenGL ES 3.0 please check back for updates. Earlier versions of Unity 5
should not be used with the Mobile SDK.
New Features
VrAPI: improved frame prediction, in particular for Unity.
Bug Fixes
Fixed prediction glitch every 64 frames.
Use correct prediction for OVR_GetCameraPositionOrientation.
Fixed location of the PlatformMenu Gaze Cursor Timer
PC Unity Integration 0.6.0.0
New Features
Disabled eye texture anti-aliasing when using deferred rendering. This fixes the black screen issue.
Eliminated the need for the DirectToRift.exe in Unity 4.6.3p2 and later.
Removed the hard dependency from the Oculus runtime. Apps now render in mono without tracking when
VR isn't present.

52|Release Notes|Unity

0.6 PC Unity Integration Release Notes

This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration that shipped with 0.6 of the Oculus PC SDK.
PC Unity Integration 0.6.0.0
New Features
Disabled eye texture anti-aliasing when using deferred rendering. This fixes the blackscreen issue.
Eliminated the need for the DirectToRift.exe in Unity 4.6.3p2 and later.
Removed the hard dependency from the Oculus runtime. Apps now render in mono without tracking when
VR isn't present.

0.5 Mobile Unity Integration Release Notes

This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration that shipped with version 0.5 of the Oculus Mobile SDK.
Mobile Unity Integration 0.5.1
Overview of Major Changes
The most significant change in 0.5.1 is to System Activities event handling in Unity. The 0.5.0 code for handling
System Activities events in Unity was doing heap allocations each frame. Though this was not a leak, it would
cause garbage collection to trigger much more frequently. Even in simple applications, garbage collection
routinely takes 1 to 2 milliseconds. In applications that were already close to dropping below 60 Hz, the
increased garbage collection frequency could cause notable performance drops. The event handling now uses
a single buffer allocated at start up.
As with Mobile SDK v 0.5.0, Unity developers using this SDK version must install the Oculus Runtime for
Windows or OS X. This requirement will be addressed in a future release of the SDK.
Bug Fixes
Rework System Activities Event handling to prevent any per-frame allocations that could trigger Garbage
Collector.
Known Issues
For use with the Mobile SDK, we recommend Unity versions 4.6.3. The Mobile SDK is compatible with Unity
5.0.1p2, which addresses a problem with OpenGL ES 3.0, but there is still a known Android ION memory
leak. Please check back for updates.
Mobile Unity Integration 0.5.0
Overview of Major Changes
The Mobile Unity Integration is now synced with the Oculus PC SDK 0.5.0.1 Beta. Please ensure you have
installed the corresponding 0.5.0.1 Oculus runtime; it can be found at the following location: https://
developer.oculus.com/downloads/

Unity|Release Notes|53

VrPlatform entitlement checking is now disabled by default in Unity; handling for native development is
unchanged. If your application requires this feature, please refer to the Mobile SDK Documentation for
information on how to enable entitlement checking.
New Features
Synced with the Oculus PC SDK 0.5.0.1 Beta.
VrPlatform entitlement checking is now disabled by default.
Bug Fixes
Health and Safety Warning no longer displays in editor Play Mode if a DK2 is not attached.
Known Issues
For use with the Mobile SDK, we recommend Unity versions 4.6.3, which includes Android 5.0 - Lollipop
support as well as important Android bug fixes. While the Mobile SDK is compatible with Unity 5.0.0p2
and higher, several issues are still known to exist, including an Android ION memory leak and compatibility
issues with OpenGL ES 3.0. Please check back for updates.
Mobile Unity Integration 0.5.0
Overview of Major Changes
The Mobile Unity Integration is now synced with the Oculus PC SDK 0.5.0.1 Beta. Please ensure you have
installed the corresponding 0.5.0.1 Oculus runtime; it can be found at the following location: https://
developer.oculus.com/downloads/
VrPlatform entitlement checking is now disabled by default in Unity; handling for native development is
unchanged. If your application requires this feature, please refer to the Mobile SDK Documentation for
information on how to enable entitlement checking.
New Features
Synced with the Oculus PC SDK 0.5.0.1 Beta.
VrPlatform entitlement checking is now disabled by default.
Bug Fixes
Health and Safety Warning no longer displays in editor Play Mode if a DK2 is not attached.
Known Issues
For use with the Mobile SDK, we recommend Unity versions 4.6.3, which includes Android 5.0 - Lollipop
support as well as important Android bug fixes. While the Mobile SDK is compatible with Unity 5.0.0p2
and higher, several issues are still known to exist, including an Android ION memory leak and compatibility
issues with OpenGL ES 3.0. Please check back for updates.

0.4 Mobile Unity Integration Release Notes

This document provides an overview of new features, improvements, and fixes included in the Oculus Unity
Integration that shipped with version 0.4 of the Oculus Mobile SDK.

54|Release Notes|Unity

Mobile Unity Integration 0.4.3

New Features
New Mobile Unity Integration Based on Oculus PC SDK 0.4.4
Mobile Unity Integration 0.4.2
Overview of Major Changes
If you are developing with Unity, we recommend updating to Unity 4.6.1, which contains Android 5.0 Lollipop
support.
We would like to highlight the inclusion of the new Mobile Unity Integration with full DK2 support based on
the Oculus PC SDK 0.4.4. As this is a significant API refactor, please refer to the Unity Development Guide:
Migrating From Earlier Versions section for information on how to upgrade projects built with previous versions
of the Mobile Unity Integration.
API Changes
Fix for camera height discrepancies between the Editor and Gear VR device.
Moonlight Debug Util class names now prefixed with OVR to prevent namespace pollution.
Provide callback for configuring VR Mode Parms on OVRCameraController; see OVRModeParms.cs for an
example.
Mobile Unity Integration 0.4.1
Overview of Major Changes
Added support for Android 5.0 (Lollipop) and Unity Free.
New Features
Added Unity Free support for Gear VR developers.
Mobile Unity Integration 0.4.0
Overview of Major Changes
First public release of the Oculus Mobile SDK.
Bug Fixes
Unity vignette rendering updated to match native (slightly increases effective FOV).
Unity volume pop-up distance to match native.
Migrating From Earlier Versions
The 0.4.3+ Unity Integrations API is significantly different from prior versions. This section will help you
upgrade.
API Changes
The following are changes to Unity components:

Unity|Release Notes|55

Table 3: Unity Components

OVRDevice OVRManager

Unity foundation singleton.

OVRCameraController OVRCameraRig

Performs tracking and stereo rendering.

OVRCamera

Removed. Use eye anchor Transforms instead.

The following are changes to helper classes:

Table 4: Helper Classes
OVRDisplay

HMD pose and rendering status.

OVRTracker

Infrared tracking pose and status.

OVR.Hmd Ovr.Hmd

Pure C# wrapper for LibOVR.

The following are changes to events:

Table 5: Events
HMD added/removed

Fired from OVRCameraRig.Update() on HMD connect

and disconnect.

Tracking acquired/lost

Fired from OVRCameraRig.Update() when entering

and exiting camera view.

HSWDismissed

Fired from OVRCameraRig.Update() when the Health

and Safety Warning is no longer visible.

Get/Set*(ref *) methods

Replaced by properties.

Behavior Changes

OVRCameraRigs position is always the initial center eye position.

Eye anchor Transforms are tracked in OVRCameraRigs local space.
OVRPlayerControllers position is always at the users feet.
IPD and FOV are fully determined by profile (PC only).
Layered rendering: multiple OVRCameraRigs are fully supported (not advised for mobile).
OVRCameraRig.*EyeAnchor Transforms give the relevant poses.

Upgrade Procedure
To upgrade, follow these steps:
1. Ensure you didnt modify the structure of the OVRCameraController prefab. If your eye cameras are on
GameObjects named CameraLeft and CameraRight which are children of the OVRCameraController
GameObject (the default), then the prefab should cleanly upgrade to OVRCameraRig and continue to work
properly with the new integration.
2. Write down or take a screenshot of your settings from the inspectors for OVRCameraController,
OVRPlayerController, and OVRDevice. You will have to re-apply them later.
3. Remove the old integration by deleting the following from your project:

OVR folder
OVR Internal folder (if applicable)
Moonlight folder (if applicable)
Any file in the Plugins folder with Oculus or OVR in the name

56|Release Notes|Unity

4.
5.
6.
7.
8.
9.

Android-specific assets in the Plugins/Android folder, including: vrlib.jar, libOculusPlugin.so, res/raw and
res/values folders
Import the new integration.
Click Assets -> Import Package -> Custom Package
Open OculusUnityIntegration.unitypackage
Click Import All.
Fix any compiler errors in your scripts. Refer to the API changes described above. Note that the substitution
of prefabs does not take place until after all script compile errors have been fixed.
Re-apply your previous settings to OVRCameraRig, OVRPlayerController, and OVRManager. Note that the
runtime camera positions have been adjusted to better match the camera positions set in the Unity editor. If
this is undesired, you can get back to the previous positions by adding a small offset to your camera:
a. Adjust the camera's y-position.

a. If you previously used an OVRCameraController without an OVRPlayerController, add 0.15 to the

camera y-position.
b. If you previously used an OVRPlayerController with Use Player Eye Height checked on its
OVRCameraContoller, then you have two options. You may either (1) rely on the new default player
eye-height (which has changed from 1.85 to 1.675); or (2) uncheck Use Profile Data on the converted
OVRPlayerController and then manually set the height of the OVRCameraRig to 1.85 by setting its yposition. Note that if you decide to go with (1), then this height should be expected to change when
profile customization is added with a later release.
c. If you previously used an OVRPlayerController with Use Player Eye Height unchecked on its
OVRCameraContoller, then be sure uncheck Use Profile Data on your converted OVRPlayerController.
Then, add 0.15 to the y-position of the converted OVRCameraController.
b. Adjust the camera's x/z-position. If you previously used an OVRCameraController without an
OVRPlayerController, add 0.09 to the camera z-position relative to its y rotation (i.e. +0.09 to z if it has
0 y-rotation, -0.09 to z if it has 180 y-rotation, +0.09 to x if it has 90 y-rotation, -0.09 to x if it has 270 yrotation). If you previously used an OVRPlayerController, no action is needed.
10.Re-start Unity
Common Script Conversions
OVRCameraController -> OVRCameraRig
cameraController.GetCameraPosition() -> cameraRig.rightEyeAnchor.position
cameraController.GetCameraOrientation() -> cameraRig.rightEyeAnchor.rotation
cameraController.NearClipPlane -> cameraRig.rightEyeCamera.nearClipPlane
cameraController.FarClipPlane -> cameraRig.rightEyeCamera.farClipPlane
cameraController.GetCamera() -> cameraRig.rightEyeCamera
---------------------------------------------------------------------if ( cameraController.GetCameraForward( ref cameraForward ) &&
cameraController.GetCameraPosition( ref cameraPosition ) )
{
...
to
if (OVRManager.display.isPresent)
{
// get the camera forward vector and position
Vector3 cameraPosition = cameraController.centerEyeAnchor.position;
Vector3 cameraForward = cameraController.centerEyeAnchor.forward;

...
----------------------------------------------------------------------

Unity|Release Notes|57

OVRDevice.ResetOrientation();
to
OVRManager.display.RecenterPose();
---------------------------------------------------------------------cameraController.ReturnToLauncher();
to
OVRManager.instance.ReturnToLauncher();
---------------------------------------------------------------------OVRDevice.GetBatteryTemperature();
OVRDevice.GetBatteryLevel();
to
OVRManager.batteryTemperature
OVRManager.batteryLevel
---------------------------------------------------------------------OrientationOffset
Set rotation on the TrackingSpace game object instead.
---------------------------------------------------------------------FollowOrientation
---------------------------------------------------------------------FollowOrientation is no longer necessary since OVRCameraRig applies tracking
in local space. You are free to script the rigs pose or make it a child of
another GameObject.