Guide for Building VR for Gear VR with Unity
Below is a step-by-step guide for creating and publishing VR in Unity for Gear VR. The guide is intended to help VR Hackathoners ramp up quickly. The guide is geared toward Mac users because ITP/NYU people were raised on Macs. As an evolving document, more tips and troubleshooting may be added.
If you're a PC-user, please read Matt Ratcliffe's excellent Guide to Building Gear VR Projects in Unity 5 - which has easy-to-follow images.
WARNING: If you're using Mac, Unity 5.1.1f, Oculus Mobile 0.6.0.1, Android free and Gear VR, only one eye renders. See Troubleshooting note 3 below. Unity is working on this bug now. You may have to roll back to an earlier version of Unity (4.6) and use Oculus integration plug-ins.
I. Prepare PhoneSTEP 1: On phone – go to Home > All Apps > Settings > System > About Device – Scroll down to Build number. Press Build number 7 times. You will be informed that Developer options has been enabled. NOTE: The Samsung phones being used for VR Hackathon NY have been prepped for developers. If you're a non-hackathoner, you may need to install USB drivers for your Samsung phone (ex. Samsung USB drivers for Windows) as well as unlock developer settings on your phone by going to Settings. STEP 2: Enable USB debugging. This will allow the tools to install and launch deployed mobile VR apps over USB. STEP 3: Download SideloadVR DeviceID to generate a device ID for your phone: https://play.google.com/store/apps/details?id=com.skyworxx.sideloadvrdeviceid You will need this ID for an Oculus signature file. Unity requires the Oculus signature file to build/run your mobile VR app for Gear VR. Note: You can also use adb devices etc via your terminal - but for the hackathon, don't waste time and just use this fast DeviceID app. STEP 4: Generate Oculus signature file at: https://developer.oculus.com/osig/ - Sign up for an Oculus account (free) to generate this file. Once you have downloaded this file, put it on your desktop. Put a COPY of OCULUS SIGNATURE FILE when creating a Unity VR project here: [YourProjectFile]/Assets/Plugins/Android/assets |
Additional ResourcesMatt Ratcliffe's Guide to Building Gear VR Projects in Unity 5 Creating a Gear VR app in Unity Free Gear VR - Setup, Tutorial, App Management (Windows) Creating a playable VR environment with Unity and Samsung Gear VR. Darshan Shankar's Developing cross-platform VR apps for Oculus Rift and GearVR Oculus: Squeezing performance out of your Unity VR game Josh McCormick’s analysis of the compositor on Metaversing: The Valve/Oculus Layered Compositors (Magic Glue for VR) |
II. Download and install Dev Kits and Applications
STEP 1: Download Oculus Mobile SDK.
TIP: You may need to change security settings re opening applications from unidentified developers to allow your computer to access Oculus files.
STEP 2: Download Android Studio.
Once installed, click Configure > Quick Start > SDK Manager. This will open the SDK Manager. Check the boxes for: Android SDK Tools, Android SDK Platform-tools, Android SDK Build-tools, SDK Platform, ARM EABI v7a System Image, Android Support Library and Google USB Driver.
Write down the path to the Android SDK because Unity asks for this path on your first build. On a Mac, it should be: /Users/[USER]/Library/Android/sdk/
STEP 3: Download JDK – Java SE Development Kit.
TIP: You’ll also need to input path to the JDK when doing a build in Unity. Do yourself a favor and make a shortcut alias to the folder on your desktop – you’ll usually find the JDK via the path below:
/Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/Contents/Home/
Again, once Unity knows where to find the JDK, you won't be prompted for its file path on subsequent builds.
Go into environment variables and set up a system variable. which allows Android Studio to use the Java SDK. Find the bin location of your JDK library - /Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk. Add "bin" to the file path. On a Mac, if you're not comfortable using the terminal, you can download RCEnvironment. It's an easy app to set environment variables. (Read the ReadMe text!) Put the RCEnvironment.prefPane file into the Preference Panels folder of the Library. Go to System Preferences and click on RCEnvironment icon. A panel will pop up. Input into key field: STUDIO_JDK. Input into value field: /Library/Java/JavaVirtualMachines/jdk1.8.0_45.jdk/bin. Then, Save.
STEP 4: Download Unity 5.1.1.
1) The latest release has OVR (Oculus VR) components and preferences already built in. If you have an old version of Unity free, replace it with the new version.
2) Install the Oculus Unity integration package from the Oculus Mobile SDK into your Unity project. While in Unity, go to Assets > Import Package > Custom Package. You'll find the Oculus Unity integration package at ovr_mobile_sdk_0 > VrSamples > Unity > Unity Integration - see image below:
3) Drag the OVRCameraController or OVRPlayerController prefab into the scene of your Unity project. See image below. Make sure to raise the OVRPlayerController above the floor of your set or it will sink into the abyss when you hit "play".
Watch this tutorial on how to use the new OVR elements (drag and drop) in Unity - "Creating a playable VR environment with Unity and Samsung Gear VR."
III. Build Settings in Unity
1) In Unity's Build Settings dialog, set the platform to Android and Set Texture Compression to ETC2 (GLES 3.0).
2) Select Player Settings and select the Android tab. Check to make sure the Default Orientation has been set to Landscape Left. In Unity 5.1.1, this setting has been selected for you.
3) Select the Splash Image section. In Unity 5.1.1, the Splash page has also been selected for you. It should be unselectable - or black.
4) In Player Settings, click on Forward Rendering and Multithreaded Rendering. Select Other Settings, check the Virtual Reality Supported checkbox.
5) Go to Edit menu > select Project Settings > select Quality Settings. In the Inspector, set Vsync Count to Don't Sync. Again, in Unity 5.1.1., this has already been done for you.
6) Go to Edit menu > select Project Settings > select Time. For Fixed Timestep and Maximum Allowed Timestep, input "0.0166666" (which is 60 frames per second).
7) Note: You can leave the AndroidManifest.xml file as is for the purposes of the VR Hackathon. If you want to submit your VR application/experience/game to Oculus for official release, you'll have to change some of these settings as specified in the Oculus Mobile Submission Guidelines document.
8) Go to File menu and select Build Settings. Add the Main.scene to Scenes to Build. After verifying that Android is your Target Platform, click on Build and Run with your Android phone plugged into your computer via USB. You'll be asked to specify a name and location for the .apk (Android application package - which is your mobile VR app).
9) Once the build is done, your VR app (APK) will show up on your phone with your Android apps, NOT in the Oculus home menu. An icon will materialize on your phone. Then, a dialog box will pop up, prompting you to insert your phone into Gear VR. Put on the headset and enjoy your VR app!
IV. Troubleshooting Tips
1) If your InputManager is generating errors, try replacing the InputManager.asset file with this version or do a Save As... The InputManager.asset file can be found in the Project Settings folder of your Unity project.
2) Error building Player: CommandInvokationFailure: Unable to convert classes into dex format. See the Console for details. If you get this error, please go to this thread: Unable to convert classes to dex format - Android issue - http://forum.unity3d.com/threads/unable-to-convert-classes-to-dex-format-android-issue.197061/
For a concise description of the problem, note this comment in the thread: "First off, for general knowledge, DEX is the process that takes code files (whether it's your code, or code that is provided in libraries) and converts it into the DEX format (Dalvik Executable). Libraries are only used for convenience during development: when you build your game, there's no notion of libraries anymore - it's all just compiled code. For this reason, when 2 or more libraries reference the same library (contain 2 copies of a referenced JAR) or define a class with the same name, this issue occurs. For example: if you are using 2 plugins in your Unity project and both contain a copy of GooglePlayServices.jar, DEX will fail to build your game, since it will try to process multiple copies of the same class. In your case, it is not clear whether this is the case (multiple copies of the same jar) or whether it's multiple copies of the same class. The first one is easier to spot (look for multiple copies of the same JAR). the 2nd one is trickier but it will help if you provided some more information (e.g: is there any extra information in the Unity console? the DEX tool should provide the name of the class that causes the failure for example)."
In plain speak, you've got duplicate JAR files. Because Unity doesn't discriminate and mushes these files together, you're screwed on a build. Get rid of duplicate files.
3) Only ONE EYE renders - see warning above. Unity 5.1 + Android free are not yet up to speed. See Unity thread: http://forum.unity3d.com/threads/mac-unity-5-1-1f-oculus-mobile-0-6-0-1-and-gear-vr-only-shows-left-eye.335568/.
Unity: "In 5.1.1p1 when trying to make a GearVR application with Android Personal there is currently a bug with our code. Even when you are using Native GearVR in Unity, the splash is searching for the OVRmanager and OVRCameraRig in your project because of this bug. The splash is intended to use the Native support. I have implemented a fix for this bug, and we are working to get it in for 5.1.1p2.
Because of this, you will not be able to deploy to GearVR with Android Personal on 5.1.1p1. The specific error that you are seeing in your project is that you are using Native support and you have OVRCameraRig and OVRManager scripts in your project. Because of this, The OculusPlugin will take control of the context during the splash screen and when the Native Plugin tries to then use the context in your main scene, it fails.
Until we get this critical fix in, you will need to use the Oculus Legacy Plugin with 5.1.1p1. Sorry."
Patch 5.1.1P2 has been released. You can give it a shot!
