Unreal Mobile Development

Overview

Unreal versions 4.10 and later provide built-in support for Oculus mobile development. Projects configured for VR automatically apply stereoscopic rendering and orientation tracking. Once your environment is set up with the appropriate tools and your project settings are configured properly, you may build virtual reality projects targeting Android, load APKs on your mobile device, and play them on the Oculus Mobile platform.

Oculus Mobile SDK

Oculus provides a mobile SDK with native C/C++ libraries for Android development in addition to supporting mobile development for game engines such as Unreal. It is not necessary for Unreal developers to download or install the Mobile SDK, but we recommend looking through our Mobile SDK Developer Guide for general information on Gear VR development such as application signature, basic mobile development tools such as adb and Oculus Remote Monitor, and performance guidelines.

We recommend that Unreal mobile developers review the following sections:

• Mobile SDK Getting Started Guide
• Mobile Development Basics
• Mobile Best Practices
• Testing and Troubleshooting

Developers interested in lower-level details about how the mobile VR rendering pipeline is handled by our native libraries may wish to download the mobile SDK and review the headers, particularly for the VrApi, which is responsible for returning headset orientation data and applying distortion, sensor fusion, and compositing.

Mobile Environment Setup

There are two ways to set up your environment for Gear VR development for Unreal: 1) using the Codeworks for Android installation package (recommended), or 2) using the standard Android SDK.

Epic strongly recommends using the Codeworks for Android 1R4 installation package rather than the stock Android SDK. Using this package simplifies Unreal set up and may be necessary to successfully build Gear VR projects. However, it requires uninstalling any standard Android SDK installation and may interfere with development using other engines or IDEs that require the standard Android SDK. To install Codeworks for Android 1R4, follow the instructions in Epic’s Required Android Setup guide.

To prepare for Gear VR development using the standard Android SDK, follow the instructions in our Mobile Android Development Software Setup for Windows guide to install the Java Development Kit (JDK), Native Development Kit, and Android SDK. Unreal developers do not need to install Android Studio. Our Unreal SDK does not currently support OS X or Linux.

Once you have installed the required Android tools, follow the setup instructions described in the Device Setup guide in our Mobile SDK documentation. In this process you will enable Developer Options on your mobile device and make a few device configuration settings.

Application Signing

Oculus mobile applications must be signed by two different signatures at different stages of development. An Oculus Signature File (osig) is required for your application to run on Gear VR, and an Android distribution keystore is required for submission to the Oculus Store.

Once you add an osig to the appropriate Unreal directory, it will be added automatically to every APK that you build. You will need one osig for each mobile device.

To add your osig to Unreal for development:

1. Follow the instructions in Application Signing to download your osig.
2. Navigate to the directory <Unreal-directory>\Engine\Build\Android\Java\.
3. Create a new directory inside \Engine\Build\Android\Java\ and name it assets. The name must not be capitalized.
4. Copy your osig to this directory.

When you are ready to build an APK for submission to release, we recommend that you exclude the osig in your APK. To do so, select Edit > Project Settings > Android, scroll down to Advanced APKPackaging, and verify that Remove Oculus Signature Files from Distribution APK is checked.

Before building your final release build, create a new Android keystore by following the “Sign Your App Manually” instructions in Android's Sign your Applications guide. Once you have generated your distribution keystore, go to Edit > Project Settings > Platforms > Android, scroll down to Distribution Signing, and entered the required information.

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

Configure Unreal for Android SDK

If you do not have a project prepared but would like to try out the process, you may use create a scene with starter content such as the C++ First Person project.

Once you have installed the Android SDK and required tools, configure Unreal for Android development.

1. Select Edit > Project Settings.
2. In the Project Settings menu on the left, go to Platforms and select Android SDK (not Android - we will configure that later).
3. Configure all fields in SDKConfig with the appropriate paths to the necessary tools. Note: if you installed Codeworks for Android, these fields should be populated automatically.

Project Configuration

This section describes how to configure any C++ or Blueprints Unreal project targeting desktop or mobile for use with Oculus mobile devices.

If you do not have a project prepared but would like to try out the process, you may use create a scene with starter content such as the C++ First Person project.

1. Select Edit > Plugins.
2. Select Virtual Reality.
3. Verify that the Enabled check box is checked for Gear VR. If you need to select it, click Restart Now in the lower-right afterward. Close Plugins configuration.
4. Select Edit > Project Settings.
5. Fill in any other desired information in Project > Description.
6. In the Project Settings menu on the left, go to Platforms and select Android.
7. Under APKPackaging, set the Minimum SDK Version to 21, and set the Target SDK Version to 21.
8. Scroll down to Advanced APKPackaging. Then:
   1. Check Configure the AndroidManifest for deployment to GearVR.
   2. Verify that Remove Oculus Signature Files from Distribution APK is unchecked, unless you are building a package to release.
9. In Engine > Rendering, uncheck Mobile HDR in the Mobile section. Restart project if prompted to do so.
10. Close the Project Settings configuration window.

Building and Running Projects

1. Connect your Samsung phone to your PC via USB.
2. Open a shell terminal and verify that your device is communicating with your PC using adb devices. Note that depending on the device you are using, you may need to configure your connection for software installation. For more information, see Adb in our Mobile SDK Developer Guide.
3. We recommend using ASTC compression, though ETC2 will also work. Select File > Package Project > Android > Android (ASTC).
4. When prompted, browse to the destination folder where you would like your APK to be installed.
5. Once the build process is completed, navigate to the destination folder. Run the .bat file beginning with Install_ to install the application to your phone.
6. Once the build process is complete, your application will be visible on your mobile devices under Apps. Note that it will not be visible in Oculus Home.
7. Click the application to launch. You will be prompted to insert it into your Gear VR headset.

Launching a Project Directly onto your Phone

You may also directly build and launch an application to your phone without saving the APK locally.

1. Connect your phone to your PC by USB.
2. Select the Launch menu from the Unreal toolbar and select your phone under Devices. If you do not see your phone listed, verify your USB connection, and check if you need to set your connection to Connected as an Installer - some Samsung phones default to Charge Only connection.
3. Your application will build and install to your Android device. When the build is complete, you will be prompted to insert the phone into your headset to launch.

Workflow

We recommend setting your phone to Developer Mode, so you can run VR apps on your phone without inserting it into the Gear VR headset. This allows you to quickly review your progress on the device without much overhead.

You may also launch the engine with a configuration option to use the GearVR plugin and Mobile renderer on the PC. This allows you to preview mobile development from the desktop using an Oculus Rift. To do so, disable OculusRift and SteamVR plugins for your project, and add -OpenGL -FeatureLevelES2 to your command line.

To run your app during development, we generally recommend connecting your phone via USB, selecting the Launch pulldown menu, and then selecting your phone under the listed devices. Particularly if you are modifying maps and shaders but not changing the code, this is often much faster than building an APK.

It is possible to preview a Gear VR application in the Oculus Rift during development. However, it is not generally useful to do so, because Rift applications are subject to substantially different performance requirements (see "Performance Targets" in Testing and Performance Analysis in Unreal). You may find it easiest to use the 2D preview in Unreal, and then either build an APK or use Launch on Device when you need to view the app in VR.

Blueprints

We provide Blueprints for common Gear VR operations such as querying battery level and headphone connection status. To access Blueprints for Gear VR, you must enable the Gear VR plugin in Edit > Plugins > Virtual Reality.

For more information, see Blueprints.

Multi-view

Multi-view is an advanced rendering feature for Gear VR, available in experimental form in Unreal 4.14 and later. If your application is CPU-bound, we strongly recommend using multi-view to improve performance.

For more information, see Multi-View (Mobile) in Advanced Rendering.