This tutorial is now quite out of date. Once we have time, we will update it with the correct steps, so please keep that in mind when reading through.
I’ve been wrestling with the GearVR for over a month now and finally have it working obediently with Unity 5. I have collected here the tips and tutorials I went through to get it working and hopefully this will get other people up to speed for the Mobile VR GameJam.
Please note I am assuming the GearVR has already been set up with your phone, if not follow this: https://www.youtube.com/watch?v=T_z5sLijIPg . Also this is for Windows only.
Setting up your Android environment.
This video on eVRydayVR really helped me but a lot of the software he discusses is now out of date: https://www.youtube.com/watch?v=0vkRtsaP3co . There are a lot of steps but you should only need to do all this once.
Note – If all else fails you can download the official Oculus Mobile documentation here : http://static.oculus.com/sdk-downloads/documents/Oculus_Mobile_Unity_Integration_Guide_0.5.0.pdf
1) Download and install the latest Java SDK (software development kit) from here: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html (take a note of the installation folder you will need this later). You will not need the JDK with demos and samples, just the JDK itself.
2) Download and install Android Studio : http://developer.android.com/sdk/index.html
It should detect the JDK we just installed above during the wizard. If not, point it to our JDK bin path. Also, keep a note of where you install the Android SDK as you will need this later. Uncheck start when it finishes installing, we have one more step.
3) You will need to go into environment variables and set up a system variable, this will allow Android Studio to use the Java SDK we just installed. You will need the bin location of your JDK library. For example mine is C:\Program Files\Java\jdk1.8.0_40\bin
4) Fire up the SDK Manager
To do this, open up Android Studio > Configure > SDK Manager.
5) And check and install the following.
Please note they are already installed on my machine here.
6) Make sure you have installed the USB drivers for your Samsung phone. These can be found here: http://developer.samsung.com/technical-doc/view.do;jsessionid=1nV1V0PSL1JJgNQ5GskhvTZkgQLs7TPHv3DfLbZdd61S61JpQKKL!-323993684?v=T000000117
Here are some instructions on how to actually install the drivers: https://developer.android.com/tools/extras/oem-usb.html
For anyone with a contract phone you can also install the drivers from this page by entering your phone’s model number (which I believe is on the battery in the phone): http://www.samsung.com/us/support/downloads
If you are like me and have bought an unlocked Samsung Note 4 in the UK then I have found that installing Kies first http://www.samsung.com/uk/support/usefulsoftware/KIES/ helps. It will install a SAMSUNG/USB drivers folder which will work with our UK phones. You can install the drivers manually (via update driver / have disk in device manager).
7) Set the phone into development mode before plugging it in with these steps:
Unlock developer settings by going to Settings.
Tap About Device and then tap the Build Number 7 times (yes 7 times!).
Then in developer settings (right above About Device), enable USB Debugging.
Finally, attach the phone by USB and make sure it is unlocked.
You will be prompted by your phone to authenticate the connection to your PC (this is important! If you ignore this and it disappears the phone will not work with the PC – this tripped me up!). The phone should be working if it appears in your removable storage / portable devices section in my computer. Lastly, it is recommended to disable any code locks for debugging with the GearVR.
Setting up Unity 5.
Although it is recommended to stick with Unity 4.6 for the GearVR, I wanted to take advantage of Enlightens fancy GI baking tools so after some experimentation I now have the Unity 5 environment working nicely. However, there are still a few bugs that we need to navigate around to get this to work, hopefully Unity will fix these in due course.
Please note I am using Unity version 5.0.1f1 (64-bit).
1) First we need to make sure our Android environment is working correctly. Start with a fresh scene. This is quite important as I tried pulling in the Oculus SDK into an old scene and hit all sorts of problems.
2) Download the SDK from Oculus here: https://developer.oculus.com/downloads/#version=mobile-0.5.0 (you will need to be logged in). You will also need the Oculus runtime installed on your machine (thanks Lloyd O. Sparkes, Jr) https://developer.oculus.com/downloads/#sdk=pc
3) Open up Unity 5 and import the package UnityIntegration.unityPackage (can be found here mobile_0_5_0\VrUnity\UnityIntegration).
4) Overwrite your project settings folder with the ProjectSettings folder included with the SDK (this is in the same folder as the Unity package above. This will make sure all the settings for Android are correct.
5) Go into Edit > Project Settings > Player. Set Company Name and Product Name.
5) Find the OVR folder in your project view then go to > Prefabs. Either drag in OVRCameraRig (static camera) or OVRPlayerController (dynamic camera).
6) Finally we need to create a signature file. You will need your phone’s id in order to do this. First download this app onto your phone: https://play.google.com/store/apps/details?id=com.skyworxx.gearvrnote4deviceidgrabber . This will give you your device id, keep this safe. Next go to this link on the Oculus site https://developer.oculus.com/osig/ , log in and input your device id, you will then receive your signature file. In your Unity project folder, place this file into Assets\Plugins\Android\assets . (If there is no assets folder in the Android folder then create one and place it in there.) This signature basically authorises your Unity project on that particular phone.
7) Now we will do a quick test with our scene. Throw in a plane and a cube for example. Go into Build settings and switch the platform to Android. Set texture compression to ETC 2 (GLES 3.0).
Then hit build and run with your Android phone plugged in via USB. Once the build has finished the phone should prompt you to plug it into the GearVR. Put on the headset and there we go, our first app!
If for some reason that didn’t work, scroll down to the bottom where we play with the Android SDK features and see if you can detect your device. Also, Unity may ask to install updated SDK versions. This is fine let it do it’s thing.
So if that all worked then well done, that’s all the set up sorted. Let’s take a break and watch something calming for a few minutes before diving into Unity 5’s new features.
Baking with Enlighten.
As we need to keep everything optimised we will need to bake EVERYTHING! Unfortunately we do need to jump through a few hoops in order to get this work. Basically we set the platform to PC, bake everything to lightmaps and switch back to the Android environment and shaders. Hopefully this will be fixed in future patches by Unity (pretty please!).
You can download the project I am using as an example here to see how things work: https://www.dropbox.com/s/9oc5glt2xng23z5/GearVRUnity5.zip?dl=0
Note – You will notice a few more lightmaps in the GearVRUnity5\Assets\testscene\testscene folder. This was because I upped the detail for my final bake to get rid of the blurry shadows. Also don’t forgot to stick your signature file into the Android/Assets folder.
1) Make sure you are in the PC, Max & Linux Standalone platform. This enables us to use all the bells and whistles and bake this into a lightmap. We want to change our rendering path from forward to deferred rendering (you can find this by going File > Build Settings > Player Settings > Other Settings). This will enable us to have shadows from multiple light sources during the bake. We will also need to go into the quality window (edit > project settings > quality) and set the project to “Riftastic” (this should have all been set automatically when we overwrote the project settings folder earlier). Make sure your shadows are set to very high settings. (see images below).
2) After a lot of testing I have found that the “Legacy Shaders/Lightmapped/Diffuse” shaders work well enough. This enables you to bake effectively in your scene and it will work well in our Android environment. Obviously you can use the shaders with spec and normal maps but this will affect performance. You will also need a cubemap to get that lovely GI. You can take any existing image (jpg, exr) and change it’s texture type to cubemap. We can then use this in the lighting window to provide subtle ambient lighting to our scene.
3) Once we have our scene set up we add our lighting that we want to use, make sure you have set your lights to mixed. Also, any objects you want to be included in the bake will need to be set to static.
4) Now we can start setting up our lighting. We will be using realtime GI in order to get our basic lighting correct then switching to baked GI. We make sure Ambient GI is set to “Realtime” and then “Precompted Realtime GI” is checked. We add our cubemap (in my scene this is Tokyo_nightside) in the Skybox slot and then add our direct light as the sun (although this isn’t necessary).
5) Once we are happy with the rough lighting. We switch to a bake. We change Ambient GI to “Baked” and uncheck “Precomputed realtime GI”. Set the baked resolution to something like 20 – 100 (warning, setting this to something like 150+ can really slow bake times down but gives us sharper shadows and AO). Set Ambient Occlusion to 1 in the “Baked GI settings (this gives extra shadow detail and is up to you). In “General GI” we can change “Atlas size” if we want better use of the texture space. You can check your outputted lightmaps here to see how efficient it is (in the Lightmaps tab at the top of the window). Now hit the build button and then go make a cup of tea / coffee, you’ve earned it!
6) Once we have baked the scene we can now switch off all the lights . Once this is done, we will need to switch to our Android platform before we can build, but before we do this we have to make changes to every texture in our scene, including our lightmaps. There is a nasty bug in Unity 5 regarding texture conversion to Android friendly compression. If you let Unity do the conversion it may take hours or even freeze the program, not good. Therefore we will need to find every texture image in our scene and manually set Android compression settings. Most importantly set the quality dialogue to normal or even better fast. DO NOT set this to best unless you fancy waiting a couple of hours for the image to convert. Even more importantly hunt down all .EXR and .PSD files. If these are not manually converted they will freeze the scene on conversion. It seems that the parser built into 5 might not be multi-threaded so you have been warned! Hopefully this will be fixed in future patches.
7) Ok, with our scene now all nicely baked like a fresh loaf out the oven, we need to switch back to our GearVR friendly environment. Make sure you do these steps:
- Set the quality settings back to “RiftAndroid” (edit > project settings > quality).
- Set our rendering path back to “forward rendering” (File > Build Settings > Player Settings > Other Settings).
- Switch the platform back to Android with texture compression set to ETC 2 (GLES 3.0). (File > Build Settings).
8) Unity will think for a bit but it should not take too long converting the scene over as we have manually done it’s job for it… Once that’s done, run and build again and test on the phone.
Note – Another option is create another project that is set to PC platform, lightmap all your models in there, set the textures and export out as a package before bringing it into your Android project. This way you only need to worry about selected meshes and textures and not converting the entire scene each time.
Build to the GearVR wirelessly
I was getting a tad concerned about the poor USB port on the phone but luckily we can build to the phone wirelessly using the Android Debug Bridge or ADB for short. This gives us a host of command-line utilities to make our lives a little bit easier.
These are based on a couple of helpful posts on the net and are the main commands I use on a day to day basis. The first is from a very helpful developer Drash over on the Oculus forums : https://forums.oculus.com/viewtopic.php?f=67&t=18021 & from a blog post by Head Trip Games: http://www.headtripgames.com/blog/1/2/year .
1) To get started we need to find the location where we can use our command line batch files. If you do not know how to create .BAT files then please look here: http://www.makeuseof.com/tag/write-simple-batch-bat-file/ . The folder we want is called platform-tools. This should be located within our Android SDK folder that we took a note of earlier. We execute our .bat files from within the platform-tools folder.
2) Now we need to set up the phone so it can communicate with the ADB over wireless. To do so, we need to install an app on the device called ADB Wireless (no root) by Henry : https://play.google.com/store/apps/details?id=za.co.henry.hsu.adbwirelessbyhenry&hl=en . Once this is active (and our phone is connected to the wireless) we need to hit the big great grey button and it will give us our phone’s ip address.
3) With our phone ready to go we will need to plug it in via USB. Then we create our first .bat file to check whether the device is connected. Add this to the batch file and call it something like “checkdevices.bat”:
This will scan for any connected devices and you should see them listed (with your device id that we found earlier).
4) Next is to connect the device to our PC via the wireless. To do this use the following code in the batch file and name it something like “connecttowireless.bat”:
adb tcpip 5555
adb connect 192.168.0.3
Obviously replace the ip address (192.168.0.3) with what ever the app gave you above. This will connect the phone over the TCP/IP socket and then your i.p. address. Finally it will list devices again. If you see your ip address in the device list then it has successfully connected over the wifi.
5) Next is to deploy our Unity builds over wireless. So, with our phone still connected via USB build and run to the device. Once finished, plug it into the GearVR, test it but do not exit your app. Now all you will need to do is rebuild in Unity and it should build via the wireless to the phone, magic!
6) If we want to have a log file for debugging purposes then we can do this too. Create a batch file called something like “capturelog.bat”:
adb logcat -c
adb logcat -s Unity:D > E:\AndroidLog\android_log.txt
I have found it’s best to put a folder somewhere simple i.e.
E:\AndroidLog\android_log.txt. You will need to put in a dummy text file with the name you have referred to in your batch file otherwise it will throw an error. Once the app is running you will get an output log of what’s going on, very handy!
7) If things go a bit wonky, which they sometimes do, you can reset and restart things quite easily too. I have 2 batch files called “resetADB” and “disconnectWireless”:
adb disconnect 192.168.0.3
8) Finally, if you want to install your app directly to your device you can create a batch file named something like “installapk”:
adb uninstall com.Oculus.UnitySample
adb install test.apk
Note – you will need to disconnect from the wireless connection first otherwise this throws errors. Also it is important to uninstall your apk first as it will not overwrite it when installing so be sure to include the uninstall in the batch file.
This will clear an old install you may have, note the “com.Oculus.UnitySample” is the name of the app you gave in Unity under File>Build Settings> Player Settings> Other Settings> Bundle Identifier . The install command will look for the location and name of the apk that we have set when we build within Unity (I build straight to my Android SDK folder so I have no directory in mine. Once this is done, you can look in your phone and find the app installed so you can demo remotely. This is by no means an exhaustive list of the commands you can do, check the links for more.
So that turned into quite an epic blog post. I have to tried to capture every step I needed to be comfortably working and building in the GearVR environment. It really is an exciting platform, Oculus have done a smashing job with it and I can’t wait to see what comes out of the the various game jams and talented folk out there.
I hope people find this useful and it gets them up to speed quicker than I did. Long live VR!