How to set up Unity for Gear VR development
Virtual reality development is a fast-moving target. New versions of hardware, game engines, SDKs, drivers and support tools are coming out all the time. Preparing to build a Gear VR game at Nordic Game Jam later this week, I found it hard to find up to date instructions on how to setup my development machine to build a Gear VR game in Unity.
Unity recently added a convenient “Virtual Reality Supported” setting. Oculus makes the package Oculus Utilities for Unity available with a custom camera rig. Unity provides a fantastic VR Samples project, also with a custom camera rig. However, you don’t need any of these custom camera rigs in your project for VR to work on the Gear VR — just check “Virtual Reality Supported” and the default camera works with head tracking out of the box. Once you go beyond basic experimentation, you will almost certainly want to make a custom camera rig using those provided by Oculus or Unity as a starting point.
Dependencies for building a Gear VR project in Unity
What you do need before you can build your Gear VR project in Unity, publish it to your phone and see it in the Gear VR headset, is to setup your development machine, phone and Unity properly. This article explains exactly what steps you need to take to get there.
Install the correct Unity version
The newest version of the Oculus runtime is currently 1.3. The only version of Unity that works correctly with this runtime for Gear VR projects is Unity 5.3.4p1. You can download this version of Unity here.
(These exact version numbers will probably be obsolete almost before I can publish this article, but bear in mind that the newest version of Unity might not always be right one to use for VR development.)
Patch Unity’s Oculus plugin
While Oculus stresses that you must use Unity 5.3.4p1 for their 1.3 runtime, they also point out that you need to override Oculus plugin that comes with that version of Unity and replace it with the one they provide in their OVRPlugin 1.3.0 for Unity 5.
Unpack the downloaded file and replace Unity’s “oculus” directory with the downloaded “oculus” directory. On OSX, the directory is located by default at “/Applications/Unity/Unity.app/Contents/VR”, while it can found at “C:\Program Files\Unity\Editor\Data\VR\oculus” on Windows by default.
Install the Android SDK
It should come as no surprise that you need the Android SDK to build a Gear VR project in Unity. You can download it here and place it anywhere you like on your computer. In Unity, navigate to “Unity” > “Preferences” and select the “External Tools” tab. Click the “browse” button for Android SDK and select the directory where you placed the Android SDK.
Install the Java Development Kit
Unity also needs the JDK to be able to build an Android project. You can download it here, and Unity will in most cases automatically detect it after a restart. You can verify it by navigating to “Unity” > “Preferences” and select the “External Tools” tab where “Android JDK” should now be filled out. If it isn’t, building a project for the Android platform should have Unity auto detect the path.
Publishing a Gear VR project to the phone from Unity
The steps above should let Unity build an android application package (“.apk”) on your development machine. You also want to see your game running in the Gear VR, however, and that requires a few more steps.
Download an Oculus Signature File (osig) for your phone
You need to sign your Gear VR application before it will run on the phone. In a terminal window, go to the directory where you installed the Android SDK. Change into the “platform-tools” directory and run this command (omit the prefixed “./” on Windows): “./adb devices”.
Go to https://developer.oculus.com/osig/ (make sure you are logged in with your Oculus Developer account) and paste the device id output from the command above into the input field. Create the folder structure “/Plugins/Android/assets/” in your Unity project. Click the “Download File” button and save the file in the folder you just created.
Enable development mode on your phone
If you have done any Android development with your Gear VR-compatible phone before, you can skip this step. Otherwise, unlock the phone and connect to the computer via USB. Approve any prompts on the phone to trust the computer and grant it access.
In Windows 7, 8 and 10, most Android phones will be immediately recognized when you connect them, whereas on OSX you will need to install Android File Transfer to get the phone properly connected.
Then follow these steps to enable development mode.
Build and run the project
That’s it, you are ready to build your project and publish it to your phone! Press Command/Ctrl + B or go to “File” > “Build & Run”. Give the package any name and save it anywhere on your computer.
If all the steps above have been completed successfully, you should — once the build and publishing process in Unity completes — be prompted to insert your phone into the Gear VR and see the scene.
You now have an app on your phone with the name you have configured Unity to use. Unity will update this app whenever you “Build & Run” the project with the phone connected via USB.
Easing your development workflow
While Unity supports previewing games directly on an Oculus Rift, you will have go through the “Build & Run” cycle every time you need to test your Gear VR game. This is a bit of a painstaking process, especially since you have to disconnect your phone from the Gear VR to connect it via USB, and then put it back into the headset.
Here are two optional steps you can take to make your development workflow easier.
Enable VR developer mode on your phone
The VR developer mode will allow you to view the game directly on the phone screen without inserting it into the Gear VR. However, you will not be able to look or move around as this typically relies on the sensors and touchpad in the Gear VR.
Follow these steps to enable VR developer mode.
Publish over WiFi
You can publish an updated build directly from Unity to the phone without removing it from the Gear VR headset by using WiFi instead of USB to push the updated game.
Install ADB wireless (no root) from the Google Play Store on your phone, connect it to your computer via USB and run the app. Follow the on screen instructions, which tell you to run:
./adb tcpip 5555
./adb connect [device IP]
Remember that the adb command is in the “platform-tools” directory of your Android SDK install directory and omit the prefixed “./” on Windows.
Build & Run the project once while the phone is connected via USB. On the following builds you can keep your phone in the Gear VR and it will automatically restart with the new build once the Unity is done building and publishing it over WiFi.
Casper Fabricius is co-founder of Cimmerse — Sell more with 3D, VR & AR. Coming from 17 years of experience as a fullstack web developer he has become an expert in WebVR and is an A-Frame contributor. He tweets abouts VR and coding as @fabricius.
If you liked this article, you may also like:
