Skip to main content

Oculus Go Unity Setup (Quick Start Guide)

In this tutorial I am going to show you how to setup your Unity development environment to create, build and install apps on the Oculus Go headset.

The objective is to cut to the chase and provide clear steps. By the end this tutorial you should be able to build the Oculus examples and get them running on the Oculus Go headset.

Assumptions​

  • You own or have access to an Oculus Go headset
  • You have played around with Virtual Reality (VR)
  • You are familiar with IDE’s
  • You may have used Unity before
  • You are using a Windows machine (explained next)
  • You have enough rights on your machine to install software
  • You understand that this is about the Oculus Go standalone headset and NOT the Oculus Rift

Why you need a Windows machine​

I’ve worked on many Web projects and I prefer using my Mac. But there are several reasons why you are much better off using a Windows machine when developing apps for the Oculus Go (and preferably one with a good GPU) :

  • Oculus has made it clear they don’t officially support the Mac with statements in their forums
  • I have also run into issues with Unity where things broke after a Mac OS update and discovered it was low on their priority list
  • To get real power out of a Mac you need an external GPU

You may already be aware that under the hood Oculus Go apps are Android apps, similar to GearVR apps. So you would think that that means you can develop on Windows or a Mac. But there are subtle differences. If the Oculus or Unity teams aren’t focused on testing or fixing them, you could end up hitting a wall. I’m telling you this from personal experience.

Step 1: Signup as a Developer​

Before you can access the headset with your computer or develop apps, you need to signup as a developer here:

https://developer.oculus.com

If you are working with an established group of Oculus Go developers, ask the admin of their Organization to grant you access. You should then receive an email invitation.

If you are working independently you can create your own Organization here:

https://dashboard.oculus.com/organization/create

Step 2: Put your Oculus Go into Developer Mode​

Please note that you must have joined or created an Oculus developer organization before proceeding. If you haven’t done that yet, see previous instructions.

When you setup your Oculus Go, it should have asked you to install the Oculus App on your smartphone (iOS or Android).

  • Turn on your Oculus Go
  • Enable Bluetooth on your smartphone
  • Open the Oculus app on your smartphone
  • Click on Settings
  • Select your Oculus Go headset listing in the app
  • Wait for it to say “Connected”
  • Expand the headset listing on the app to display additional menu items
  • Click on More Settings
  • Click on Developer Mode
  • Enable Developer Mode

Step 3: Install the Java JDK​

Oculus Go apps are based on Android. Android uses Java. You won’t need to write any code in Java. But you will need to have the Java JDK installed in order to build Android apps.

You can download the Java JDK from here (for Windows download the x64 version):

http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

Step 4: Put the JDK on your path​

Find the path of the jdk bin folder​

  • Using File Explorer find the C:\Progam Files\java folder
  • Look for a folder starting with “jdk” (not jre)
  • If there are multiple jdk folders select the one with the highest version number
  • Open the bin subfolder
  • Click in the File Explorer navigation bar to highlight the path
  • Copy the path to the clipboard

Add the jdk path to your environment path​

  • On your Windows 10 task bar, type into Ask me anything: Control Panel
  • Select Control Panel (Desktop app)
  • Click System
  • Click Advanced system settings
  • Click Environment Variables …
  • Scroll the System Variables list and look for a variable named PATH
  • If PATH doesn’t exist, add a new variable
  • Edit or set PATH to include the path that you copied to the clipboard

Test the jdk path​

  • Open up a command prompt (it must not be one that was open already)
  • Run this command: javac -version
  • If you get an error there is an issue with your path

Step 5: Setup adb – Android Debug Bridge (Windows 10)​

If you are familiar with Android development you probably know about adb – the Android Debug Bridge. It’s a command line tool supplied by Google for managing, installing and debugging builds on Android devices attached to a development computer by a USB cable. You can also use adb to install and uninstall apps to and from the Oculus Go headset. You can setup Unity to install apps to the headset for you when you build and run your app.

To get setup, you need to do the following:

  • Install the Oculus Go adb driver
  • Download the Android SDK command line tools
  • Put adb on your path
  • Test that adb is on your path

Step 6: Install the Oculus Go adb driver​

Browse to this link:

https://developer.oculus.com/downloads/package/oculus-go-adb-drivers/

  • Check the box to agree to the terms
  • Click the Download button
  • Unzip the file (don’t just view contents!)
  • Find the .inf file
  • Right-click
  • Click Install

Step 7: Download the Android SDK command line tools​

Browse to this link:

https://developer.android.com/studio/#downloads

  • Scroll down to Command line tools only
  • Download the sdk-tools-windows zip file
  • Extract the contents
  • Create a new folder, such as C:\android-sdk
  • Move or copy the tools folder from the extracted download under C:\android-sdk
  • Open up a command prompt
  • Change to C:\android-sdk\tools\bin
  • Run this command: sdkmanager platform-tools
  • Press y for Yes at the prompt
  • Run this command to install the USB drivers: sdkmanager “extras;google;usb_driver”

Step 8: Put adb on your path​

  • On your Windows 10 task bar, type into Ask me anything: Control Panel
  • Select Control Panel (Desktop app)
  • Click System
  • Click Advanced system settings
  • Click Environment Variables …
  • Scroll the System Variables list and look for a variable named PATH
  • If PATH doesn’t exist, add a new variable
  • Edit or set PATH to include:
  • C:\android-sdk\platform-tools\ and C:\android-sdk\tools\bin

Step 9: Test that adb is on your path​

  • Open up a new command prompt (the changes won’t take effect for any command prompts that were already opened)
  • Type: echo %PATH%
  • Make sure that the path to platform-tools is included in the PATH output by the echo command
  • At the command prompt, type: adb devices
  • Don’t worry if no Android devices were found

Step 10: Download and Install Unity​

For the examples in this tutorial you can download the Personal (Free) version of Unity. To do so, follow this link:

https://unity3d.com/get-unity/download

Install Android Support​

When installing Unity be sure to install Android support.

Step 11: Plug your Oculus Go into your computer​

Your Oculus Go comes with a charger and cable. Like most phone chargers these days it’s also a USB cable.

Turn your Oculus Go on and be ready to jump in and out of it while going through these steps:

  • Open up a command prompt and run: adb devices
  • Remove the adapter from the Oculus Go cable
  • Plug the small end of the cable into the Oculus Go (the same port you use for charging)
  • Plug the other (USB) end into a USB port on your computer
  • If at any point in the process you are asked to grant permission by either your computer or the headset, grant it
  • To list your device and makes sure that it is connected, again run: adb devices
  • Put on your Oculus Go
  • If it just shows the charge level and goes black, be sure to turn the Oculus Go completely on by holding down the power button until the Oculus logo appears in the headset
  • In File Explorer expand This PC
  • Under Devices and drive you should see VR-Headset listed (if not, run adb devices again)
  • Look around Internal Shared Storage

Accessing Internal Storage​

For development, the only time you will need to access Internal Storage on your Oculus Go will be when you want to access a screen shots or screen recordings. You can also push pictures and video (mp4) files to your Oculus Go and they will be available for viewing.

Here are some folders that might be of interest:

  • oculus / Screenshots – screenshot made using Sharing / Take Photo – you can also place PNG and JPEG files here to view them in the Gallery

  • oculus / VideoShots – screen recordings made using Sharing / Record Video – you can also place your own MP4 files here and play them through the Gallery

  • Download – where files go if they are downloaded from the Oculus browser

  • DCIM / .thumbnails – thumbnails used by the Oculus Go Gallery

Dragging files onto your Go is not how you install builds. That will be covered later.

If your Oculus Go can’t find it’s controller​

When messing with the settings, sometimes the Oculus Go suddenly can’t find it’s controller. You may also run in this after pairing with a game controller.

If the controller can’t be found, you have a few things you can try:

  1. Hold down the Home (Oculus symbol) button on the controller and see if it can finally connect
  2. Hold down the Back and Home buttons on the controller for several seconds to try to pair again
  3. Try rebooting the headset
  4. Try completely powering the headset off and then powering it back on
  5. Open up the Oculus app on your smartphone and first unpair the controller then pair it again (you may need to take the battery out of the controller and put it back in)
  6. If none of this works put in a fresh controller battery and try all of the above again

Even though I’ve seen people try a factory reset to get it to connect again, I think that’s rather extreme. The steps above will hopefully resolve the issue.

Step 12: Create an Oculus Go project​

To create an app in Unity that runs on the Oculus go you will need to create an Android app with VR support.

  • Launch Unity
  • Click: New
  • Set Project name to: oculus101
  • Make sure that Template is set to 3D
  • Set Location to a folder where you would like to keep your Unity / Oculus projects
  • Click: Create project
  • From the main menu select Window / Layouts / Default

Step 13: Setup Unity External Tools​

Here are the steps to map Unity to the Android and Java SDKs. You should only need to do this once.

  • From the main menu select Edit / Preferences
  • Click the External Tools tab
  • In the Android section set:
  • SDK to C:\android-sdk using the browse button
  • JDK to C:/Program Files/Java/jdk… using the browse button to select the latest version of the jdk that is under the Java folder

Unless you’ve upgraded the JDK, you should not have to setup the External Tools again.

Step 14: Set the build settings​

  • From the main menu select: File / Build Settings …
  • Under Platform select Android
  • Click Player Settings …
  • This will open the player settings in the Inspector panel
  • Set Company Name to your name or company

Step 15: Set Other Settings​

  • Still in the Inspector, expand Other Settings
  • Under Identification set Package name to something unique, preferably reversing a domain name that you own (like com.example.oculus101 – but don’t use ‘example’)
  • If you don’t own a domain make up something unique
  • Set Minimum API Level to Android 7.1 ‘Nougat’ (API Level 25)
  • Set Target API Level to Automatic (highest installed)

Step 16: Set XR Settings​

  • Still in the Inspector, expand XR Settings
  • Check Virtual Reality Supported
  • Under Virtual Reality SDK’s click the + (plus) sign and add Oculus

Step 17: Build the app​

  • Back in the Player Settings window, click Build (this sometimes needs to be done to lock in the settings)
  • Create a new folder under your current project and call it builds
  • Save the build in the builds folder as oculus101
  • This will create a file called oculus101.apk in the builds folder
  • If Unity asks to upgrade the Android SDK to finish the build, grant permission and take a break while it runs the update

This build isn’t ready to be installed on the Oculus Go yet. A few more steps need to be taken before it will work

Step 18: Import the Oculus Utilities for Unity package​

To build apps for the Oculus Go you will need to download and import the Oculus Utilities for Unity package which can be found here:

https://developer.oculus.com/downloads/package/oculus-utilities-for-unity-5/

If that link no longer works or you are working with a different version of Unity, select what you need from this link:

https://developer.oculus.com/downloads/unity/

Keep this file in an easy to remember place. When you download a new version, be sure to still keep the old version. You may run into issues with a new version that can be easily resolved by reverting to the old version.

Import​

  • In File Explorer right-click on the download and select Extract All…
  • Expand the OculusUtilities folder (in the extracted folder, not the zip file!)
  • Drag the OculusUtilities.unitypackage file (the extension may be hidden) onto the Unity Project window Assets folder
  • If it won’t go, make sure you aren’t dragging from the zip file folder view
  • The Import Unity Package dialog box should pop up (if you have multiple screens it may pop up on another screen)
  • Click the Import button
  • If you get a warning titled Update Oculus Utilities Plugin, click Yes
  • If you get a Restart Unity popup, click Restart

Import Troubleshooting​

If the Import Unity Package dialog doesn’t come up, make sure it didn’t end up on another screen or under another window.

If for some reason drag and drop doesn’t work you can import the package by doing the following:

  • Right-click in the Project window on the Assets folder
  • Select Import Package / Custom Package …
  • Browse to the location of the *.unitypackage file
  • Click Open
  • Follow the remaining steps above

Step 19: Connect the headset​

  • Connect the headset to your computer using the USB cable

  • Make sure that it is on (it should be okay if it’s on, but asleep)

  • Open up a terminal window / command prompt and type:

    adb devices

  • You should see the headset listed as an alphanumeric number that matches what comes up in the Oculus app

Step 20: Build and run the Cubes example​

  • In the Assets folder expand Oculus / VR / Scenes
  • Double-click on the Cubes scene
  • From the Unity main menu select File / Build Settings …
  • Click Add Open Scenes
  • In the Scenes in Build list uncheck all but the Cubes scene
  • Click Build And Run
  • Click Save
  • If prompted, click Replace
  • Wait for the Build Successful message

Step 21: Put on the headset​

Your headset should still be attached to your computer – so be careful. Especially if you are using a laptop.

You may see the Enter VR calibration screen. If so, pick up your controller and hold the Home (Oculus) button down the way you usually do.

You may see the Made with Unity screen and then the cubes demo. Turn your head to look around.

Step 22: To Exit​

To exit the app, Double-click the Home button on your controller and select Quit.

Congratulations!​

You created your first Oculus Go app!

Build and run the Room example​

Now repeat the steps above for the Room scene.

The Room scene uses the controller. If the headset has been sitting idle it may lose track of the controller. If that happens hold the Home button on the controller down for a few seconds. Look down and you should see a box that moves as you wave around the controller.

Build and run the GearVrControllerTest example​

Oculus has updated the GearVrControllerTest scene to detect if the app is being run on an Oculus Go. Follow the steps above to build for that scene.

When running the scene, you will see a text panel that changes depending on what buttons you press on the controller.

If you look down you will see a VR image of the controller that matches the orientation of the controller in your hand. It’s made to look like the real Oculus Go controller.

Build and run the UI example​

If you build and run the UI scene you will see a simple dialog box. Look at a position on the sliders or checkbox and click the trigger button on the controller.

Build and run the Trivial example​

The Trivial scene is just what it’s name implies. A trivial scene that contains only a white cube. It serves as an example of all you need to get a scene working. A camera, an object and some light.

Where is the app?​

During the development phase you will find the app on your Oculus Go in the Library, under Unknown Sources.

Bundle Identifier​

When creating the app, you were instructed to create a unique package name in the build settings (like com.example.oculus101).

This was set in the build settings under Other Settings / Identification / Package nameYou may see multiple pages of unknown sources. It seems to be sorted by bundle id (com.example…) and not the label. Filter through the pages until you find your app.

Click on the app in the listing to launch it again, even if your headset is not attached to your computer. Once a *.apk file is installed on your headset, you no longer need to be attached to the computer to run it.

Installing and uninstalling via the Command Line​

If you are developing an app, Unity can handle installing the build on your headset for you. But if you or someone else wants to install an existing build, firing up Unity is overkill.

You or someone else can install a build from the command line. You can even uninstall a build from the command line to save space. This can be handled through adb.

Listing the device​

Plug your headset into your computer through the USB cable. Then run this command to make sure it is connected:

adb devices

If you would like a bit more info you could try this command too (that’s a lowercase L at the end of the command):

adb devices -l

Installing a build from the command line

If you see multiple devices when you run adb devices, you have to cut and paste the id of the headset to the clipboard. Otherwise adb won’t know which device to install to.Open up a command prompt and change the directory to the location of the *.apk file (such as \projects\oculus101\builds). Assuming that you called the file oculus101.apk, run this command (substitute DEVICE-ID for your device id):

adb -s DEVICE-ID install -r oculus101.apk

Be sure to include the -r flag or it will fail to replace the existing build.If you have no other devices listed, including the emulator, then you can just do this.

adb install -r oculus101.apk

Listing packages on the device​

You can list all of the packages on a device using this command (substitute DEVICE-ID):

adb -s DEVICE-ID shell pm list packages -f

The problem is that there are a lot of packages so you need to either redirect the output to a file or filter it by bundle id.

Uninstalling a build from the command line​

The uninstall command requires the bundle id (Package Name), like this (substitute DEVICE-ID and bundle id (com…)):

adb -s DEVICE-ID uninstall com.example.oculus101

If you get an error either you entered a non-existent bundle id or the build was already uninstalled from the device.

References​