How to get started with Oculus Quest and Unity on macOS
Get the right Unity version
There’s lots of versions of Unity and just grabbing the latest isn’t going to get you very far. The various moving parts involved all rely on each other being at certain specific versions.
So to get started install Unity Hub from here.
Once Unity Hub is installed, select “Installs” and you should see something like this… (but without the listed installs)
Click “ADD” and choose 2019.1.4f1.
A quick note about the versions — my day to day development environment is normally Apple’s Xcode, this means my gut instinct is to grab the latest verision. At the time of writing the latest Unity version is 2019.3.0a3 and the next latest is 2019.2.0b3 the thing to be wary of is that the a and b in both of these version codes refer to Alpha and Beta versions of Unity. From my trial and error it is possible to get something working with the Oculus Quest but you will struggle with getting the Oculus Integration compiling/working.
Modules
When installing the Unity version(s) ensure that you have the following included:
As the Oculus Quest is an Android device you will need Android Build Support and the SDK/NDK tools. Make sure you expand the tree to confirm both are selected (by default the SDK & NDK Tools aren’t selected).
Create a new project
Using Unity Hub go to “Projects” and click “NEW”, if you have installed multiple versions of Unity you can use the down arrow next to “NEW” to select the version we added in the previous step (2019.1.4f1).
Select “3D” and give the project a name and location, hit “CREATE” and wait for your new project to appear.
Oculus Integration
Now your new project has been created head to the Asset Store and search for “Oculus”. The first result should look something like this:
Press “Import” and a dialog will appear asking what to import, by default everything is selected so just press “Import”. This will likely take some time.
When it’s done you will probably see this dialog:
Go ahead and press “Yes” and you’ll be asked permission to restart Unity, allow it to do it’s thing.
When Unity has restarted and your project is back on screen you should now have some Oculus specific options in the menu bar.
If you don’t have this, double check you created the project with the correct version of Unity.
If you do have it, leave it alone for now, we’ll come back to it shortly.
Project Settings
We need to set out project to build for Virtual Reality and more specifically, in the case of the Quest, we need to set it to build for Oculus VR on Android.
To do this go to the Edit menu and select “Project Settings”. In the window which appears (which should already be set to Player in the left hand column), select the Android tab in the right hand area, find the XR Settings and tick “Virtual Reality Supported”.
Use the “+” button to add Oculus
Notice the warning stating “XR is currently not supported when using the Vulkan Graphics API.”. This tripped me up, i initially treated this as a throw away warning. It’s not, you’ll just get an empty space if you run in this configuration. So while we’re in the Project Settings we’ll fix this.
Go to “Other Settings” and notice the “Graphics APIs” list:
Select “Vulkan” by clicking it and then press “-” to remove it from the list.
While in this section there’s another thing we need to fix, the Oculus Quest needs a minimum Android API level of 19 but by default the minimum is set to 16. Scroll down, find “Minimum API Level” and set it to “Android 4.4 ‘KitKat’ (API Level 19)”.
Add an Oculus API key
Remember those new menu items for Oculus we got earlier? Go to “Oculus” > “Platform” > “Edit Settings”
You’ll now see a couple of big red errors that we’re going to fix…
Click the button that says “Create / Find your app on https://dashboard.oculus.com”, perhaps unsurprisingly a browser window will be opened taking you to the Oculus dashboard for your account. If you don’t have an account you will need to create one to proceed.
In the browser window click “Create new app” and you will be asked which platform, at the time of writing the Quest isn’t an option, however the Go & Gear VR are close enough so select that option.
Give it a name, you probably want this to be the same as your project name, and then hit “Save and Continue”. The next screen will give you the all important App ID, copy this and paste it in to Unity in the “Application ID”, “Oculus Rift” and “Oculus Go/Quest or Gear VR” settings boxes within the Oculus Platform Settings.
You’ll still have an error on this panel, to fix it untick “Standalone Platform” and it should go away.
Build Settings
Though we’ve configured the player for the Quest (by setting some android preferences and telling it to use the Oculus SDK) we haven’t actually told Unity to build for Android.
To do this, go to “File” > “Build Settings”…
Select “Android”, change “Texture Compression” to “ASTC” and press the “Switch Platform” button. This will take some time…
Really quite some time.
Hook up the Quest
Before actually connecting your headset to the computer you need to put your Quest in to developer mode (as you might with any Android device you were trying to run code on).
Developer Mode
Hopefully the user account you’re logged in to on the Quest is the same as the one you added a development app to earlier. This then allows the Oculus app on your mobile phone to toggle Developer Mode on the headset.
Open the Oculus app on your phone, go to the Settings tab and hopefully you can see your headset listed.
Tap the Quest headset and you should see the following:
Tap “More Settings” and “Developer Mode” should be listed here, toggle this on.
Connecting
Connect the Quest to your computer using a USB cable.
The first time you do this you’ll get a dialog in the headset asking permission to allow the connected computer to access the Quest. You’ll need to put on the headset and use the controller to allow permission.
If all this has gone smoothly, in Unity, you should now be able to see the Quest in the device list in Build Settings (you may need to make use of the “Refresh” button).
Running on the device
By default the open scene we have in Unity is pretty empty and boring and not set up for the Oculus.
Luckily the Oculus Integration includes some nice sample conent.
Go to the following path in the project browser…
…and double click “GearVRControllerTest”.
Notice in the Hierarchy that this is already setup with a OVRCameraRig.
Go back to “Build Settings” and press the button labelled “Add Open Scene” to put the GearVRControllerTest scene in to the build.
Now press “Build and run”, a save dialog will be shown, give it a location to save to (this is where the APK file will be built and saved to), put the headset on and then be patient — it should run up on the Quest.
Problems?
Hopefully everything ran fine.
However I have encountered times when nothing has run up, even though i’ve followed the steps above.
The two common issues I’ve seen are:
- Unity thinks it’s targetting an Oculus Go instead of an Oculus Quest.
Go to the menu bar, select Oculus > Tools > Oculus Platform Tool
Make sure that the Target Oculus Platform is set to “Oculus Quest”.
2. Somehow the Vulkan Graphics API is back in the mix
If you look in the console you might see this warning appear:
Despite explicitly removing the Vulkan API in an earlier step, sometimes it creeps back in.
Go to your Player Settings as before, find “Other Settings”, “Graphics APIs” and remove “Vulkan” from the list.
Further Reading and Acknowledgements
This article is very much reusing and combining content from other sources and wouldn’t be possible without them.
Big thanks to “Frontend Fanatics” and their video https://www.youtube.com/watch?v=eySe4Wj6xbk
and to “Circuit Stream” and their article https://circuitstream.com/oculus-unity-setup/
The Oculus documentation is also extremely valuable https://developer.oculus.com/documentation/quest/latest/concepts/book-unity-gsg/
