Unity Developer Guide
| Introduction | Unity Copyrights and Trademarks © 2015 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.
Unity | Contents | 3 Contents Introduction.........................................................................................................5 Requirements..................................................................................................................................................... 5 Installation..........................................................................................................................................................
| Contents | Unity Revision.............................................................................................................
Unity | Introduction | 5 Introduction Welcome to the Oculus Unity Developer Guide. This document describes developing Unity 3D games and applications for VR devices with the Oculus PC and mobile SDKs. A Unity integration package, sample Unity applications, and mobile SDK Unity examples are available for PC and mobile development to help you create virtual reality applications in Unity.
| Introduction | Unity considerable resources to one path. Your license choice will depend largely on the performance characteristics and distribution needs of your app. 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 Samsung EI-GP20 or other compatible controller for Gear VR.
Unity | Introduction | 7 Monitor Setup To get the best experience, you and your users should always configure the Rift correctly. In Windows 7 and Windows 8, you can change Windows' display settings by right-clicking on the desktop and selecting Screen resolution. • • It is possible to clone the same image on all of your displays. To ensure each display uses the correct frequency, Oculus recommends extending the desktop instead of cloning it.
| Getting Started | Unity Getting Started This section describes steps taken to begin working in Unity. Importing the Unity Integration If you are already working in a Unity project, save your work before beginning. First, create a new project that you can import the Oculus assets into. 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.
Unity | Getting Started | 9 Adding VR to an Existing Unity Project The Unity Integration package may be used to integrate Oculus VR into an existing project. This may be useful as a way of getting oriented to VR development, but dropping a VR camera into a Unity game that wasn't designed with VR best practices in mind is unlikely to produce a great experience. Note: This is one simple method for adding VR to an existing application, but is by no means the only way.
| A Detailed Look at the Unity Integration | Unity A Detailed Look at the Unity Integration This section examines the Unity integration, including the directory structure of the integration, the Unity prefabs are described, and several key C# scripts. Note: There are minor differences between the contents of the Unity Integration provided for PC development and the version bundled with the mobile SDK. Contents OVR The contents of the OVR folder in OculusUnityIntegration.
Unity | A Detailed Look at the Unity Integration | 11 This folder also contains the plugins for other platforms: OculusPlugin.bundle for MacOS; and Android/ libOculusPlugin.so, vrlib.jar, and AndroidManifest.xml for Android. 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.
| A Detailed Look at the Unity Integration | Unity Two scripts (components) are attached to the OVRPlayerController prefab: • • OVRPlayerController.cs OVRGamepadController.cs Figure 2: Prefabs: OVRPlayerController, expanded in the inspector 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.
Unity | A Detailed Look at the Unity Integration | 13 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.
| A Detailed Look at the Unity Integration | Unity 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. OvrCapi OvrCapi is a C# wrapper for LibOVR (specifically, CAPI).
Unity | A Detailed Look at the Unity Integration | 15 OVRMainMenu OVRMainMenu is used to control the loading of different scenes. It also renders a menu that allows a user to modify various settings in the VR framework, and allows storage of these settings for later use. A user of this component may add as many scenes that they would like to be able to have access to. OVRMainMenu may be added to both OVRCameraRig and OVRPlayerController prefabs for convenience.
| A Detailed Look at the Unity Integration | Unity You will find the following sample scenes located in Assets/Scenes: 30Hz_Sample An example of how to set the TimeWarp vsync rate to support 30Hz apps, as well as how to enable Chromatic Aberration Correction and Monoscopic Rendering for Android. For more information on 30Hz TimeWarp and Chromatic Aberration Correction for Android, please review the TimeWarp technical note in the Mobile SDK documentation. Box_Room A simple box room for testing.
Unity | A Detailed Look at the Unity Integration | 17 SaveState_Sample An example demonstrating saving the state of the game on pause and loading it on resume. Click on the objects in the scene to change their color. When you run the scene again, the objects should be in the color you had selected before exiting. Startup_Sample An example of a quick, comfortable VR app loading experience utilizing a black splash screen, VR enabled logo scene, and an async main level load.
| A Detailed Look at the Unity Integration | Unity interface guidelines and requirements, please review Interface Guidelines and Universal Menu in the Mobile SDK documentation. Control Layout: Mobile Note: This section describes control layout for the Mobile Unity Integration only. We recommend that you start by familiarizing yourself with Unity’s input system, documented here: http:// docs.unity3d.com/ScriptReference/Input.
Unity | A Detailed Look at the Unity Integration | 19 Table 4: Gear VR Touchpad Controller Mappings Button / Axis Name Input Manager Mapping / Axis Sensitivity Value Mouse 0 / Button 1 mouse 0 and joystick button 0 1000 Mouse 1 / Button 2 mouse 1 and joystick button 1 1000 Mouse X Mouse Movement X axis 0.1 Mouse Y Mouse Movement Y axis 0.1 These controller and touchpad input mappings can be set up in Unity under Project Settings > Input Manager.
| 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 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. Click on File > Build Settings...
Unity | Configuring for Build | 21 Navigate to Edit > Project Settings > Quality.
| Configuring for Build | Unity 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 4X or higher is ideal. However, if necessary, you can adjust to suit your application needs. Note: A quality setting called Fastest has been added to address a potential performance issue with Unity 4.5 and OS X 10.9.
Unity | Configuring for Build | 23 Note: The Use 24-bit Depth Buffer option appears to be ignored for Android. A 24-bit window depth buffer always appears to be created. 2. As a minor optimization, 16 bit buffers, color and/or depth may be used. Most VR scenes should be built to work with 16 bit depth buffer resolution and 2x MSAA. If your world is mostly pre-lit to compressed textures, there will be little difference between 16 and 32 bit color buffers. 3. Select the Splash Image section.
| Configuring for Build | Unity Checking Optimize Mesh Data may improve rendering performance if there are unused components in your mesh data. Configuring Quality Settings 1. Go to the Edit menu and choose Project Settings, then Quality Settings. In the Inspector, set Vsync Count to Don’t Sync. The TimeWarp rendering performed by the Oculus Mobile SDK already synchronizes with the display refresh. Figure 6: Unity Pro 4.5 Note: Antialiasing should not be enabled for the main framebuffer. 2.
Unity | Configuring for Build | 25 Configuring Time Settings Note: The following Time Settings advice is for applications which hold a solid 60FPS, updating all game and/or application logic with each frame. The following Time Settings recommendations may be detrimental for apps that don’t hold 60FPS. Go to the Edit -> Project Settings -> Time and change both Fixed Timestep and Maximum Allowed Timestep to “0.0166666” (i.e., 60 frames per second).
| Configuring for Build | Unity Running the Build Now that the project is properly configured for VR, it’s time to install and run the application on the Android device. Note: Your application must be appropriately signed or it will not run. See "Create Your Signature Files" in the Oculus Mobile Submission Guidelines for more information. 1. First, make sure the project settings from the steps above are saved with File > Save Project. 2. From the File menu, select Build Settings….
Unity | Sample Unity Application Demos | 27 Sample Unity Application Demos This section describes the sample Unity applications provided by Oculus as a reference for development. Running Pre-Built demos: PC To run the pre-built demos, download the appropriate demo zip file for the platform you need. For example, Tuscany is available here: https://share.oculus.com/app/oculus-tuscany-demo. • • For Windows, download the *demo win.zip file. For Mac, download the *demo mac.zip file.
| Sample Unity Application Demos | Unity Tuscany (PC only) Gamepad Control • If you have a compliant gamepad controller for your platform, you can control the movement of the player controller with it. • • • • The left analog stick moves the player around as if you were using the W,A,S,D keys. The right analog stick rotates the player left and right as if you were using the Q and E keys. The left trigger allows you move faster, or run through the scene. The Start button toggles the scene selection.
Unity | Best Practices: Mobile | 29 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..
| 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.
Unity | Best Practices: Mobile | 31 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.
| Best Practices: Mobile | Unity Design Considerations Please review Design Guidelines in the Mobile SDK documentation if you have not already done so. Startup 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.
Unity | Best Practices: Mobile | 33 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.
| Best Practices: Mobile | Unity 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 realtime render statistics. Figure 8: VrScene: Tuscany 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.
Unity | Best Practices: Mobile | 35 In this mode, translucent colors will accumulate providing an overdraw “heat map” where more saturated colors represent areas with the most overdraw.
| Migrating From Earlier Versions | Unity Migrating From Earlier Versions The 0.4.3+ Unity Integration’s API is significantly different from prior versions. This section will help you upgrade. For changes pertaining to Mobile SDK v 0.5, see the section at the bottom. API Changes The following are changes to Unity components: Table 5: Unity Components OVRDevice → OVRManager Unity foundation singleton. OVRCameraController → OVRCameraRig Performs tracking and stereo rendering. OVRCamera Removed.
Unity | Migrating From Earlier Versions | 37 1. Ensure you didn’t 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.
| Migrating From Earlier Versions | Unity Deprecated Use Instead cameraController.FarClipPlane cameraRig.rightEyeCamera.farClipPlane cameraController.GetCamera() cameraRig.rightEyeCamera OVRDevice.ResetOrientation(); OVRManager.display.RecenterPose(); cameraController.ReturnToLauncher(); OVRManager.instance.ReturnToLauncher(); OVRDevice.GetBatteryTemperature(); OVRDevice.GetBatteryLevel(); OVRManager.batteryTemperature OVRManager.batteryLevel if ( cameraController.
Unity | Known Issues and Troubleshooting | 39 Known Issues and Troubleshooting This section outlines some currently known issues with Unity integration that will either be fixed in later releases of Unity or the Integration package. A work-around may be available to compensate for some of the issues at this time. PC Targeting a Display To run your application on the Rift in full-screen mode, use the <>_DirectToRift.exe file located next to your standard binary.
| Known Issues and Troubleshooting | Unity After importing the latest Oculus Unity Integration package the rendering is corrupted. We require the orientation to be landscape. Check that your defaultOrientation in Player Settings is set to Landscape Left. After importing the latest Oculus Unity Integration package the app does not launch as a VR app. Ensure you have administrator rights to the system you are installing the integration to.
Unity | Revision | 41 Revision Released March 31, 2015
