Building virtual reality apps for each platform in Unity can sometimes have a few gotchas. I’ve spent the past month or so moving a Unity Google Cardboard app into Gear VR, stumbling upon a few quirks and missing a few steps. I thought I’d list the tips I’d come across after it all, to help those who attempt this after me!
The first step in getting an app running properly on Gear VR is having the correct “Build Settings” and “Player Settings” for your Unity project. This bit isn’t too complicated, but when things stop working right, it really makes you question yourself and whether you’ve got them set up right! Here are how I’ve set up my own project for Gear VR:
The settings should look like so:
Seeing the Gear VR error “thread priority security exception make sure the apk is signed” when running your app? This means your phone doesn’t see an Oculus Signature File in your Unity project build.
This isn’t too hard to generate, but if you’ve been largely working with Google Cardboard apps or you’ve switched phones mid-development, this is really easy to overlook! Your app needs to have an Oculus Signature File inside it to give your phone permission to run the VR side of things in your test app.
“All Gear VR applications must be signed with an Oculus Signature File (osig) during development to access low-level VR functionality on your mobile device. This signature comes in the form of an Oculus-issued file that you include in your application.” — Oculus, Preparing for Mobile Development
You can generate an OSIG file using the Oculus Signature File (osig) Generator. They provide full details of how to generate the file for your particular phone, just make sure you’ve got it connected over USB.
Once you’ve got it downloaded from that tool, add it into the Project/Assets/Plugins/Android/assets/ folder of your project.
Turns out, you can enable Developer Mode within the Gear VR service on your phone which lets you run Gear VR apps without needing to connect them to the headset. This was an absolute revelation when I uncovered this.
To do so:
Now here’s an interesting question — you can’t see logs when you’re wearing the Gear VR headset. You also can’t really have it connected to your PC when it’s also connected to the Gear VR headset! So… how do you see logs? The answer is actually pretty neat — you can connect to your phone’s logs over Wi-Fi!
adb tcpip 5555
* daemon not running. starting it now on port 5037 * * daemon started successfully * restarting in TCP mode port: 5555
adb connect (that IP address you just found out)
For example, if the IP address was 192.168.13.37:
adb connect 192.168.13.37
connected to 192.168.13.37:5555
It should show something like the following if you are connected successfully:
List of devices attached 192.168.13.37:5555 device
adb logcat -s Unity
If that doesn’t show the sorts of logs you are looking for, this answer in the Unity forums has a wider net of logs it can capture that can relate to Unity:
adb logcat -s Unity ActivityManager PackageManager dalvikvm DEBUG
Note: If you switch over to Wi-Fi and haven’t got your OSIG file generated yet, you will need to reconnect your phone via USB first — you can’t retrieve the device ID needed unless connected over USB.
While debugging and struggling with some bugs, I turned to editing the manifest file… that’s not the right option. Unity makes this automatically:
“During the build process, Unity projects with VR support enabled are packaged with an automatically-generated manifest which is configured to meet our requirements (landscape orientation, vr_only, et cetera).” — Unity, Building Mobile Applications
So… you can’t really hit the Play button in the Unity editor and test your app. Instead, you’ve gotta upload it onto your phone every time. This can drive you a little crazy after a while. There’s a workaround but it’s not likely to be available to everyone — use an Oculus DK2.
If you’ve got a spare Oculus DK2 around, you can actually connect it up to your computer to do quick testing without needing to export the whole project. Just plug in your DK2 and then press the Play button in Unity!
Keep in mind that this isn’t necessarily going to be exactly what it would be like on the Gear VR, so you will want to test properly on that as well:
“The rendering path for Android applications differs substantially from the rendering path used for Rift application previews and builds, and you may notice important differences in the look-and-feel and performance.” — Oculus, Preparing for Mobile Development
The latest stable version of Unity (at the time of writing) is Unity 5.5.2, however, I’ve had issues getting Gear VR projects to export and play successfully in VR mode using this version. If you’re having issues seeing your app in VR and you’ve set all the settings correct… try dropping back to Unity 5.5.1 and see if that resolves it for now.
Got any tips that I didn’t mention? Feel free to share them in the comments below or get in touch with me on Twitter at @thatpatrickguy! I’d love to hear them!