This tutorial addresses specific issues with developing for Oculus Quest in Unity using Oculus Integration for Unity 1.39 , from enabling Developer Mode on your headset to configuring your Touch Controllers.
Oculus Integration for Unity 1.39, released on July 25, 2019, modified the manifest test requirements for Quest development, breaking all applications that have not been submitted to the Oculus Store / have not previously passed the manifest test. If you are experiencing this issue and are already familiar with Quest development in Unity, the following steps will fix the issue. Otherwise, skip to Enable Developer Mode On Your Quest for a step-by-step tutorial for getting started with developing for the Oculus Quest!
In Unity, remove AndroidManifest.xml and create an Oculus Store-compatible file by navigating to:
Oculus > Tools > Remove AndroidManifest.xml Oculus > Tools > Create store-compatible AndroidManifest.xml
If you have not created an Application ID, navigate to dashboard.oculus.com and select Create New App. Enter a name for your application and select Oculus Go & Gear VR from the Platform dropdown menu. Copy and paste your unique App ID into the Oculus Go / Quest or Gear VR field in OculusPlatformSettings, accessed through:
Oculus > Platform > Edit Settings
If you are using LocalAvatar, you must also enter your Application ID in OvrAvatarSettings, accessed through:
Oculus > Avatars > Edit Settings
Rebuild and run your APK and full functionality will be restored.
Enable Developer Mode On Your Quest
First thing’s first, if you haven’t already, download the Oculus App onto your phone. This is where you will manage your Quest and all your other Oculus devices.
With the Oculus App open on your phone, turn on your Quest and follow the onscreen instructions. If you have any issues connecting your Quest to the Oculus App, refer to this guide.
Once your Quest is connected, navigate to Settings and select More Settings. In the More Settings menu, select Developer Mode and toggle the button to enable.
Enabling Developer mode will allow us to side load our VR scene onto our Quest. More on that later. For now, let’s configure our development environment.
Install Android Studio and SDK Tools
Install and open Android Studio. If prompted, select Do not import settings and click OK.
The Android Studio Setup Wizard will then launch. Follow the instructions to complete the Wizard, selecting Standard Installation when prompted.
Once installation is complete, click Configure in the bottom right corner of the welcome screen and select SDK Manager from the dropdown menu.
The minimum Android SDK Platform API Level for the Oculus Quest is 19 (Android 4.4 KitKat). We will be using SDK 23 (Android 6.0 Marshmallow) in this tutorial.
To install SDK 23, select the checkbox next to Android 6.0 (Marshmallow) and click Apply. Confirm the correct components will be installed and click OK.
Accept the License Agreement and the components will be installed. Click Finish and confirm that SDK 23 Status has changed to Installed.
Click OK to close the SDK Manager and Quit Android Studio. Unity will take care of everything from here!
Download and Install Unity
Next, we’re going to configure Unity for Quest Development. If you haven’t already, navigate to unity.com and select Get Started, then Try Personal. Accept the terms and select Download Unity Hub.
Unity Hub is a management tool that you can use to manage all of your Unity projects, installations, and licenses. You must have a Unity Developer Network (UDN) account to install and use the Unity Editor from Unity Hub. If you already have a UDN account, sign in, and choose your license type.
If you do not have an account, follow the prompts to create one. You can choose to create a Unity ID or use one of the social sign-ins.
Once you sign in, select New License Activation, select Unity Personal, acknowledge that the company or organization you represent earned less than $100,000 in gross revenue in the previous fiscal year or that you do not use Unity in a professional capacity, and click Done.
Once activation is complete, select the back arrow in the top left to return to the Projects overview screen.
Before we can create a new project, we must first install a Unity version. Select Installs in the navigation menu on the left. We want to install a new Unity version, so select Add.
In the list of Unity Versions, select Unity 2019.1.14f1 and click Next. This is the Unity version we will be using in this tutorial. Note that Oculus supports other Unity versions. If you wish to use another Unity version for future projects, be sure to review the compatibility and version requirements in the Oculus documentation.
Then, click the arrow next to Android Build Support and check Android Build Support and Android SDK & NDK Tools and click Next. This will provide Unity the ability to access the Android SDK we just installed.
If prompted, accept the terms and conditions and click Next. Installation will begin (sit back and relax, this will take a few minutes). Once installation is complete you will see the version card listed under Installs. Ensure that the Android icon is present at the bottom of the version card and click Projects in the navigation menu on the left.
Alright, let’s create a new project and dive into the Unity Editor!
Create a New Unity Project
On the Projects page, click New to create a new Unity Project.
Give your project a name and select the file path where you would like your project stored. I recommend creating a dedicated folder for your Unity projects, as Unity will automatically create a subfolder for every project you create.
Select 3D as your project template (this should be the default) and click Create. This will launch and load the Unity Editor. If prompted to download a new version, select Skip new version to keep using 2019.1.14f1.
We’re almost there. To get our Quest to play nice with Unity we have to set up Oculus Integration and tweak a few settings.
Download and Import Oculus Integration for Unity
Unity provides built-in VR support for the Oculus Quest. The Oculus Integration for Unity package adds scripts, prefabs, samples, and other resources to supplement Unity’s built-in support. We will use these resources to control our VR camera behavior and configure our Touch controllers.
To install, navigate to:
Window > Asset Store
This will open the Unity Asset Store in the Unity Editor.
Type Oculus into the Search for assets field and select Oculus Integrationin the list of results.
Scroll down and click Download to download the package (this may take a few minutes, depending on your connection). Once the download is complete, select Import (the Download button will change to Import).
The Unity Editor will then decompress and unpack the package. Ensure that all checkboxes are checked in the Import Unity Package window and select Import in the bottom right corner of the window (again, this will take a few minutes).
If prompted, update the Oculus Utilities and Spatializer Plugins. Unity will restart and you will notice an Oculus dropdown menu has been added to the menu bar. Let’s move on to the next step!
Install Oculus Android and XR Legacy Input Helpers Packages
We need to install a couple of packages to ensure our VR scene can run on the Quest. Navigate to:
Window > Package Manager
Find the Oculus Android and XR Legacy Input Helpers packages in the Package Manager and select Install in the bottom right corner of the window. If you are using an older version of Unity, XR Legacy Input Helpers may not be included in the Package Manager because they are installed by default.
Next, we will set our project’s build settings to ensure it is configured to work with the packages we just installed.
Configure Build and Player Settings
In the Unity Editor, navigate to:
File > Build Settings
In the Build Settings, select Android from the list of Platforms and ensure Texture Compression is set to ASTC. Click Add Open Scenes to add your current scene to the build and click Switch Platform (take another break, this will take a while).
Once the process completes, select Player Settings in the bottom left corner of the Build Settings window. Under Settings for Android, select Other Settings.
Under Graphics APIs, remove Vulkan and, in the Identification section, change Minimum API Level to Android 6.0 ‘Marshmallow’ (API level 23).
Still under Settings for Android, navigate to XR Settings. Check the box next to Virtual Reality Supported and add Oculus to the list of Virtual Reality SDKs.
Close the Project Settings and Build Settings windows. Now we just need to take care of a few recent issues that appeared after the Oculus Integration for Unity 1.39 update.
Create Store-Compatible AndroidManifest.xml
Oculus Integration for Unity 1.39, released on July 25, 2019, modified the manifest test requirements for Quest development, breaking all applications that have not been submitted to the Oculus Store / have not previously passed the manifest test. Previously, this was only necessary for applications submitted to the Oculus Store.
To create a store-compatible AndroidManifest.xml navigate to:
Oculus > Tools > Remove AndroidManifest.xmlOculus > Tools > Create store-compatible AndroidManifest.xml
If you use a previous version of Oculus Integration for Unity in future projects, this step may not be necessary.
Create an Application ID
Now we need to create an Application ID to link our application to our Oculus account. Navigate to dashboard.oculus.com in your browser, sign in, and select Create New App. Enter a name for your application and select Oculus Go & Gear VR from the Platform dropdown menu, then click Submit.
Copy your App ID, head back to the Unity Editor, and navigate to:
Oculus > Platform > Edit Settings
Paste your App ID in the Oculus Go / Quest or Gear VR field in OculusPlatformSettings section in the Inspector. Repeat the process for OvrAvatarSettings by navigating to:
Oculus > Avatars > Edit Settings
Congratulations, Unity is now configured to use Oculus Integration for Unity 1.39 to develop for the Oculus Quest! Now, let’s create your first VR scene.
Create Your First VR Scene
Right click under the Hierarchy and add a plane to your scene. This will give us a reference point (and something to stand on). Next, right click on the Main Camera and select Delete. We going replace it with an OVRCameraRig prefab from the Oculus Integration package.
You can add the OVRCameraRig as an individual prefab, but we are going to add it as a part of the OVRPlayerController. The OVRPlayerController is basically an OVRCameraRig prefab attached to a simple character controller.
Search for OVRPlayerController in your Assets folder and drag it to your Hierarchy.
At this point, we could Build and Run our scene and have the ability to look around with our headset and move throughout the scene using the thumb sticks on our controller. Let’s take it one step further.
Select OVRCamerRig in the Hierarchy and, in the Inspector ensure the checkbox next to Use Recommended MSAA is checked and change the Tracking Origin Type to Floor Level.
Next, let’s add a pair of virtual hands to act as our controllers. Search for LocalAvatar in your Assets folder and drag the LocalAvatar prefab into the Hierarchy under Tracking Space. With LocalAvatar selected, ensure Show First Person is selected and Show Third Person is not selected. While you’re there, deselect Can Own Microphone.
Your Hierarchy should look like the below image:
We’re finally ready to Build our scene and send it to our Quest!
Build and Run
Connect your Quest to your computer via USB and, in the Unity Editor, navigate to:
File > Build Settings
Select your Quest as the Run Device. If your Quest does not show up in the dropdown menu, select Refresh and check again. Ensure your scene is listed under Scenes In Build and click Build and Run. Choose a name for your APK and press save (this will probably take a few minutes).
Once the build is complete put on your Quest and enjoy! If your project is not running, you can find it by navigating to:
Libraries > Unknown Sources
Selecting your build will launch the scene just like any other application in your Library.
That’s it! You just built your first VR scene for Oculus Quest!
I hope you found some value in this tutorial and you are inspire to keep learning!
I’ve consolidated some links below that I found helpful along the way. I encourage you to check them out.