Oculus Quest: Quick Start for Unreal Engine

This guide covers everything you need to know to get started developing Unreal applications for the Oculus Quest.

This topic contains the following sections:

• Setup Your Device
• Select a Distribution
• Setup for Android Development
• Create a Project
• Configure the Project for Oculus Development
• Launch the App on Your Device
• Add the Entitlement Check
• Plugin Settings
• App Distribution
• Package Your App

Setup Your Device

• Set up your device for development as described in the Mobile Device Setup

Select an Unreal Engine Distribution

There are a number of ways that you can obtain the Oculus Unreal distributions.

• Binary Option: No compilation necessary, is behind the latest Oculus integrations by 1 or more versions.
• Oculus Source: The latest Oculus integrations.
• Epic Games Source: Behind the latest Oculus version by 1 or more versions, can be more stable than Oculus source.

See the Version Compatibility Reference, and Release Notes to help you choose a distribution.

1. Binary Option

You can obtain a binary distribution with the Epic Game Launcher. This Oculus code may be two or more versions behind the latest Oculus SDK, but if you are a beginning developer, choose this binary distribution. It is stable, and does not require downloading the source from GitHub, setting up Visual Studio, and compiling the entire Unreal game engine source code, which is a lengthy process. The following image shows an example:

You can also get source distributions from GitHub if you have the correct access.

2. Oculus Source Option

You can obtain the most up-to-date source distribution from the Oculus GitHub Repository. These distributions are the most up-to-date with the latest Oculus SDKs. We support the current release of UE4 and any preview of the next release of UE4. Please see the Oculus GitHub Repository table in Version Compatibility Reference, in order to choose the specific downloads that best suit your development criteria. While new Oculus features ship first to the Oculus GitHub versions, API changes may occur when these branches are merged back into Epic’s version of the engine. We recommend these distributions for professional developers who would like to access the latest Oculus SDK features. In order to build this source base, see Building UE4 from Source.

3. Epic Source Option

You can obtain a source distribution from the Epic GitHub Repository. This Oculus code may be several versions behind the latest Oculus integrations. Please see the Epic GitHub Repository table in Version Compatibility Reference, in order to choose the specific downloads that best suit your development criteria.

Setup Unreal Engine for Android Development

1. Download and setup the version Unreal Engine that you wish to use. Check the Version Compatibility Reference for the list of SDKs that ship with each version.

2. Set up Unreal 4.25 for Android Development by installing Android Studio. Unreal requires the Android SDK and NDK, Ant scripting and JDK, as well as specific environment variables, which are included with Android Studio. Note that earlier versions of Unreal required NVidia CodeWorks.

   Find instructions for installing Android Studio and uninstalling CodeWorks in Unreal’s documentation: Setting up Android SDK and NDK for Unreal.

   For older versions, of Unreal, you can find the installer for CodeWorks at the following location: https://docs.unrealengine.com/en-US/Platforms/Mobile/Android/Setup/AndroidStudio/index.html [Unreal-Install-Dir]\Extras\AndroidWorks\[Platform]\

   For example, on Windows 10, you would likely find the installer, CodeWorksforAndroid-1R7u1-windows.exe, under C:\Program Files\Epic Games\UE_4.24\Engine\Extras\AndroidWorks\Win64\. On macOS Catalina, you would likely find the installer, CodeWorksForAndroid-1R7u1-osx.pkg, under Users/Shared/[UE_VERSION_NUM]/Engine/Extras/AndroidWorks/Mac.

Create a Project

In this section you will use Unreal Engine to create a project for Oculus development.

1. From the Unreal Engine Launcher, press the Launch button to open the Unreal Project Browser.
2. From the New Project Categories section of the Unreal Project Browser, select Games, and click Next
3. One the Select Template page, choose Blank project and click Next
4. For Project Settings, choose:
   • Blueprint
   • Mobile / Tablet
   • Scalable 3D or 2D
   • No Starter Content

   At the bottom of the screen:

   • Set the folder location
   • Set the project name

   Your screen should look like this:

   
5. Press the Create Project button to create the project and load a blank project.

Configure the Project for Oculus Development

In this section, you will enable the Oculus plug in and modify some project settings to work with Oculus devices.

1. Select Edit > Plugins, choose the Virtual Reality section, and make sure that the OculusVR Plugin is enabled.

   
2. To run any Unreal Engine project when it is deployed to Oculus Quest, you must save at least one UE4 Level. To save the current Level, press the Save icon in the toolbar to save it. Give it a name, such as GoQSMap or QuestQSMap.

3. Select Edit > Project Settings. Then, under Project, select the Maps & Modes section:

   

4. Under Default Maps, set both the Editor Startup Map and the Game Default Map to the Level that you just saved:

   

5. Scroll down and select Engine > Input. Locate the Mobile section:

   

6. For Default Touch Interface, select Clear, which sets this value to None:

   

   The result should look like this:

   

7. Scroll down to the Platforms section, select Android. Then scroll down on the right-hand side to the APK Packaging section, and if necessary click Configure Now:

   

8. Set the following settings depending on your target device.

   For Quest/Quest 2:

   • Minimum SDK Version: 23
   • Target SDK Version: 25
   • Enable FullScreen Immersive on KitKat and above devices, check for True

   The following image shows an example of the settings for Quest.

   

9. Open Advanced APKPackaging and click the + next to Package for Oculus Mobile Devices. From the drop-down select Oculus Quest and Oculus Quest 2.

   

10. Click on the Android SDK section, and make sure that Android SDK tools that are needed to build your project point to the correct folder on your computer, and you have set the API levels per your device. See Setup Unreal Engine for Android Development for more info.

11. Scroll to the Engine section, select Rendering, and under Mobile and then Mobile MSAA, make sure 4x MSAA is selected.

    

12. Scroll further to the VR section of the Rendering settings and make sure Mobile HDR is turned off. The following image shows an example.

    

    Note that you may need to restart your project for some of these settings to be applied.

13. Add additional code of your choice to the project.

Note that many of the settings described in this topic are also provided in the Oculus Performance Window. For more information, see Oculus Performance Settings.

Launch the Unreal Project on a Device

This section describes how to launch your UE4 project so that it can be viewed in the Oculus Quest headset.

1. Make sure your Oculus device is connected to your development PC via the USB cable.
2. Make sure you have installed and can run the Android Debug Bridge (ADB), and that your PC can see the device using the ADB command adb devices. For more information, see ADB in the Mobile SDK Developer Guide.

3. In the UE4 Editor, click beside the Launch icon to open Options for Launching on a Device:

   
4. From the drop down list, select the device you want to deploy to. If you are prompted to save the project, make sure to do so even if you recently saved it. This will ensure that the latest content resides on your Oculus Quest.
5. In the lower corner of the UE4 Editor, a progress bar indicates the status of the packaging process. If this is the first time you are packaging your project, it could take a few minutes, depending on the size of your project.
6. When the process is complete, you should be able to launch the project and view it in your Oculus headset.

Add the Entitlement Check

All Unreal apps that ship on the Oculus Store are recommended to implement the Entitlement Check to verify that the user’s app is legitimate. For information about how to implement the Entitlement Check, please see the Unreal Development Getting Started in the Platform Solutions guide.

Plugin Settings

Configure different aspects of your Oculus app such as whether it supports hand tracking, what level of FFR it uses, and set the color space using the Plugin Settings. For more information, see Plugin Settings.

App Distribution

When you are ready to distribute your application, an Android Distribution Keystore is required for submission to the Oculus Store.

Before building your final release package, create a new Android keystore as described in the section “Manually Sign an APK” in Android’s Sign your Applications guide. Once you have generated your distribution keystore, in the Unreal Editor, go to Edit > Project Settings > Platforms > Android, scroll down to Distribution Signing, and enter the required information.

See the Application Signing section of the Mobile SDK documentation for more information.

Note: It is important to review Distribute, which covers Oculus Store submission requirements and guidelines.

Package Your App

• Oculus Quest: Compile and Package Apps This section provides in-depth information for running and deploying Unreal applications that target Oculus Quest.