vr dev

First steps for GearVR Unity development

First steps to start developing apps for the Gear VR. The following is gathered information found from different sources, and some insight from development and testing, that should give you a run through the basic requirements, installations, project setup and some development guidelines. Further references at the bottom. Some script guidelines will be added soon.


GearVR is an active VR headset that supports Samsung’s flagship devices (Galaxy, Edge, Note). The headset and device hardware/software was developed together with Oculus, and their framework is provided so that you can develop projects for both the Gear VR and the Rift – although developing for GearVR needs a bit more caution, and optimising is a bit more intensive. There are 2 ways to go about developing for GearVR in Unity, with the Oculus Utilities or without. We will go with the easy way of implementing the built-in Unity VR support* which will convert you simple camera to stereo at deployment. Although you have some more control by installing the Oculus assets, the easy way is also a bit more modular. However, most of what follows applies for both ways.

*Otherwise you need to upgrade Unity with some patches and by replacing some program folders before getting started [x].

Setup your computer for Android development

  • First you need to have the Android SDK. It can be installed manually through the Android SDK tools, but the easiest way is to just install the Android Studio which includes the SDK. Make sure to install the SDK (not the Android Studio) on a folder that is easy to find. I use C:/Develop/AndroidSDK/. On OS X,  you have to find the directory of the SDK and make a shortcut on a non-hidden location that you can link from Unity.
  • If you are not a Java developer, chances are that you will need to install the JDK as well (Java Development Kit) – The android studio installation will notify you anyway.

Check Unity Android development setup

  • Go to Unity Preferences / External tools and link the folder of the Android SDK you installed before.
  • On the second slot, link the path of the JDK. Usually Unity finds it automatically if you restart it. (On Windows the path should be ProgramFiles/Java/JDK…)
  • Go to Build Settings and Select Android, and then Switch Platform. If you haven’t included the Android platform when you installed Unity, the safe way is to re-download Unity, with Android Tools checked -otherwise you can get into compatibility issues.

Setup your phone for Development

  • To enable the Developer mode on your phone, go to “Settings / About device”, and Tap the “Build number” 7 times. It will notify you that Developer mode is enabled.
  • Go the new menu that appeared now on “Settings / Developer Options”, and enable “USB Debugging”.

Setup your GearVR-compatible phone with Unity

  • Firstly go ahead and make an Oculus account.
  • To be able to deploy your GearVR app to your phone, you need to install the GearVR app launcher (Oculus home). Since its not available from the Play Store, you need to plug your phone to your GearVR mask. When you hear the welcome message unplug it and follow the installation steps. It will require your Oculus account login.
  • The next step is to generate an “OSIG” file; a unique VR development signature tied to your phone. Generate from the Oculus Developer Tools. It requires IMEI or device serial. I will recommend using the device serial since there are a lot of cases in which osig files generated from the IMEI don’t seem to work*.  You can do that either from your computer or phone. In either case, I would suggest to keep the OSIG file on your phone storage, in case you need to use it on the go. The device number can be found in “Settings/About device” or in the box of your phone.

*If there is a compatibility problem, your app will not run, instead GearVR will pop up the VR text: “Thread Priority Security Exception. Make sure the APK is signed”. This means your OSIG file is not compatible with your phone. Try generating a new one using the device serial number.

Setup a Unity Project

  • Create an Empty 3D project.
  • In your Assets folder create the following path “Plugins/Android/assets/” and inside place your OSIG file. You can place there multiple OSIG files for all compatible phones which you might want to use.
  • From Build Settings switch to Android.

Android Player Settings 

  • Set a Company/Product Name.
  • From Other Settings set the Bundle Identifier (com.companyname.productname).
  • Minimum API, set to KitKat or higher (eg. Lollipop).
  • Multi-threaded Rendering suggested checked.
  • When building -or testing with a Rift- check Virtual Reality Support – see more below**.

Build Settings / Texture Compression

  • Set texture compression to ASTC*.

*Although recommended, we found that we can’t build textured terrains with ASTC texture compression – after the splash screen, GearVR pops up a “quit unexpectedly” error. After trying different types of build settings we found that ASTC compression seemed to be the problem, and changing to ETC2 solved it. See compression comparison here [x].

If required  – Edit/Project Settings/Time*

  • Change both Timestep and Maximum Allowed Timestep  to 0.0166666

*If you need to hold a fixed 60FPS because of your app’s game logic.

Edit/ Project Settings/Quality Settings

  • VSync to Don’t Sync
  • Anti-aliasing* suggested to set Off. Default is x2 which can run but its on the limit. x4 will decrease the FPS depending on your scene.
  • Minimize Pixel Light Count. Suggested to set to zero if possible.

*You will need to address anti-aliasing in any case. One alternative is the AA script from the Image Effects of the standard assets.

Developing and Building

That’s pretty much (almost) what you need to do, to be able to setup and start developing a GearVR app. The general logic of the new “SDK” for developing for the GearVR is that you do not need any downloaded assets from Oculus*. Just by having the OSIG file in place, and using Unity’s build-in VR support features, you can develop VR apps as mono (single) camera projects, that will convert to stereo VR when installed and run on the mobile device.

The one thing you will need to make sure, is to have “Virtual Reality Supported” checked when building. This feature will also make the project compatible with the Oculus Rift -if there is one in hand – while developing in the editor.

*Not necessarily. If required download from here [x].

Gear VR input

GearVR has a cross type trackpad and a back button which you can use as input.
The back button triggers the escape button, so you can easily program it.
Now the trackpad doesn’t offer any specific interface. It just behaves as a normal mouse. As a mouse its not really useful in VR. To effectively use it, you will need to write some code that tracks deltaTime, deltaX and deltaY movement between mouse down and up, so that you can analyse it as taps and swipes.

Uploading Apps

During the cause of development you might need to build and upload to your phone very frequently. To run your app however you need to connect it to the GearVR headset, which makes the procedure view website of plugging your device to computer, and then to the headset hideous -also plugging your device to the laptop all the time will reduce the recharge cycles of the battery. A working alternative is to use a cloud drive eg. Dropbox to upload your app from your computer and download/install it through the same drive wirelessly on your phone.

Compatibility with Google Cardboard apps

In general you can’t -and its not advised to- use your GearVR with Cardboard apps. You can do so though, by installing a Package Disabler app and disable the GearVR functionality. Then you can use the headset to run Cardboard apps, but of course you cannot use its input sensors. Another workaround is to mount the phone to the mask without hooking up the mini-USB connector, therefore using the headset passively.

Migrating from the Google Cardboard SDK projects

To modify your existing Cardboard SDK project to run with GearVR is in general simple. The main thing is replacing your Cardboard Camera Rig with a simple camera (tagged Main Camera). Though, you will miss Recentering, and the Gaze Input Module for Raycasting, that you will have to do by code, as well as other low level functionalities.

On the upside, you can freely use Skyboxes and UIs.

Further optimisation

  • Its a good practice, when working with a demanding project, to check which objects/assets/behaviours consume most of the speed/power/memory. Use the Profiler window which monitors real-time performance, and try to test your app with certain objects disabled.
  • Bake lighting and disable shadows whenever possible.
  • Double check you geometry and its topology. Low-poly models always work best.
  • Use controlled LOD (level of detail) to lower the geometry resolution with camera distance.
  • Another good idea is to invest in Occlusion Culling, for disabling rendering of specific objects that are hidden by others.
  • Last is to work with or write optimised shaders. Unity offers some non-costly Mobile shaders that cover the basics.

Stream/Record Content from Gear VR

  • For GearVR official apps, you should be able to record your screen, from the GearVR menu options. Although it doesn’t record audio, which you have to record externally through the headphones jack and then later synchronize with your video.
  • To stream video, the optimal way seems to be Google Chromecast, paired to an HDMI screen/projector/TV.

Further references:

  • Oculus Build Suggestions [x]
  • Unity – Optimisation for VR [x]
  • Made with Unity – Gear VR optimisation tips [x]
  • Unity – Introduction to VR [x]
  • Some good principles of VR design and development are described in the Google Cardboard Design Lab app [x]
  • Additional GearVR apps, not marketed from Oculus Home can be downloaded through the SideloadVR app [x]

More information scripts and guidelines to be posted soon.