Over the years I have successfully deployed my own Unreal Engine projects to: GearVR, Oculus Go, and Oculus Quest.
But it wasn’t always easy or straightforward. “Official” documentation often contradicted itself. Searching on the internet for error messages often times resulted in even more frustration as the message was a side effect and not the root cause of the problem.
Hence the need to create and share this blog post to help others trying to do the same thing but with fewer banging your head against the wall sessions.
While I will be referencing both Unreal Engine and Oculus documentation but using my own screenshots, I am also going to show a different path that I have recently tried out and haven’t seen any issues with it.
It involves using the Virtual Reality template project- but note that it does NOT say it is for Oculus Mobile. It has worked for me so far on both Oculus Go and Oculus Quest- collectively known as Oculus Mobile.
I walked through these steps in some recent presentations I have given at the Colorado Virtual & Augmented Reality Group and the Denver/Boulder Unreal Engine Group.
Please note this information is offered as-is, no warranties expressed or implied. And please take time to read through this document; you may or may not have everything your need right up front like the USB to USB-C cable for the ‘Quest.
You already have an Oculus Mobile set-up and configured using it with probably your phone on the same wireless network. Note the username you used; you will need it again below to link to a developer account. These steps will take one from a clean start to a successfully side-loaded project using a Windows desktop. I don’t have easy access to Linux or Mac but most of the steps will be similar.
Key: be sure you have the latest version of the firmware for your Oculus Mobile and the latest version of the Oculus app software on the device used to configure it. Also you will find that sometimes when you launch UE4, the Oculus desktop software might tell you to it needs to update. So just a friendly head’s up that you will be re-starting your PC early and often.
Step 1 – Install Launcher and Highest Version of UE4
Download and install “The Launcher” from https://www.unrealengine.com/en-US/ and install the latest engine. As of this writing, that is 4.24.1 Please read the EULA and also note that you will need to create a login. Please use a strong password 🙂 And re-boot your PC.
Step 2 – Install CodeWorks for Android
Install CodeWorks for Android. Please note this is a special version for Unreal Engine development and trying to install CodeWorks for Android from other sources will result in things not working correctly, trust me, I’ve tried. Note that this step will also automatically install all of the Android Device Bridge (ADB) software and drivers to connect your Oculus Mobile to your PC.
Ex: on my machine, I installed the engine on my C: and the path to Codeworks is:
C:\Program Files\Epic Games\UE_4.24\Engine\Extras\AndroidWorks\Win64CodeWorksforAndroid-1R7u1-windows.exe
Right click and Run as administrator to begin the installation process. The defaults are fine but also check the Automatically resolve dependency conflicts. NOTE!!! Please read the EULA(s) and don’t walk away; it does require manual responses during the installation. This process will download and install A LOT of software so be patient. And re-boot your PC. Basic screenshots follow.
Step 3 – Install Oculus Setup Software
Install Oculus Setup for desktop software. Even if you don’t have a desktop Oculus Rift, this software is still required. I have a Rift so this is what has worked for me. If you don’t have a Rift, then you might get by with installing just the ADB drivers as mentioned in Step 4 below. You will need to create a login. Please use a strong password. https://www.oculus.com/setup/ And re-boot your PC.
Step 4 – Oculus Developer Registration
You will need to be registered as an Oculus Developer in order to activate Developer Mode on your Oculus Mobile. While that link says Quest, it works for Go too. You can register as an individual.
NOTE!!! Be sure to use the SAME login and e-mail address as indicated in the Assumptions section on this blog post. I’ve had problems trying to use separate accounts and the same account for both has worked for me up to this point. Also note the Important section at the top of that link- since we are going to be side-loading an application, this doesn’t apply to us for now.
Follow the steps on that link above but skip the Install the Oculus ADB Drivers section.
Step 5 – Now the Fun Begins – Quick Start Guide (QSG)
While this Quick Start Guide (QSG) does work, it is seriously lacking. What do I mean by that? If you follow the steps in it, you will have a level with a gray checkered floor that you can only look around in- you can’t move around using the controllers! But go ahead and read it top to bottom as this will give you an insight into the steps required. Once you get the hang of it, it will get easier over time.
So instead of a Blank Project, in Select or Create New Project, choose Games and Next.
And on Select Template, choose Virtual Reality and Next.
NOTE!!! If this is your first project using this engine, your machine will peg its CPU for a while. It will need to compile and cache shaders. It can take several minutes. It will only do this once on this project; when you re-open it, it won’t take as long but this can catch many people by surprise because it will appear that nothing is happening. This template is intended for desktop systems but we are going to change it to work with Oculus Mobile.
Then follow along as the QSG indicates.
On QSG Step 7, also do the following. Under Supported Platforms, be sure to check Android. This is what makes the Virtual Reality Template work on Oculus Mobile instead of just desktop Windows.
Also on Step 7- change both the Editor Startup Map and Game Default Map to MotionControllerMap.
On Step 12, please click on the button that says “Accept SDK License”. If you don’t click this, when you go to package the project for deployment, it will fail.
After QSG Step 16, “Launch the Unreal Engine Project on the Oculus Quest” go ahead and try to deploy from with UE4 but you might need to do Step 6 next before it will work…
CAREFULLY turn your head with the headset on- don’t jerk the cable! The A button on the ‘Quest controller will teleport you and the palm trigger will close/open the hands.
Please note this will ONLY work with it properly connected. How to make it work w/o having a cable attached? You will need to package it and that is covered in Step 7.
Step 6 – The Dance of the Headset
Most of you will need a special cable; USB to USB-C in order to connect your Quest to your PC. You will NOT be able to use the cable that came with your Quest as that is power only and not both power and data; it is USB-C on both ends. The cable that came with the ‘Go works fine. Just be mindful that these cables can be short so don’t accidentally jerk them.
When you connect your headset to your PC with the cable, you will see a screen inside your Oculus Mobile about do you trust this device for USB debugging. You will need to select this from the device and the screen will disappear if you don’t check it. Re-starting the headset and toggling between developer mode can force it to come back. If this is not done, then ADB won’t be able to “see” the device and you won’t be able to deploy to it.
Step 7 – The Smoke Test
In order to install this Android application on Oculus Mobile, you will need to do what is called side-loading. This is a manual installation process.
Re-boot your PC so this is a clean process.
Launch your UE4 project and click on the Build button on the top toolbar. Save your project.
Under File: Package Project: Android: Android (ASTC) and it will default to your project folder. Also check the Show Output Log as this will show you what is happening. Depending on the speed of your machine, this can take a while.
You want to see the magic words: “BUILD SUCCESSFUL” at the very end. Check the Output Log if this doesn’t happen as it can give you insights as to what went wrong.
Now you will need to run an elevated command prompt and browse to the installation folder for your project.
Windows Key + X and select Windows PowerShell (Admin). Select Yes. Then type cmd to switch it into Command Prompt mode.
NOTE!!! If you do NOT select an elevated session, bizarre errors can occur, especially Java related ones. This one step has saved me (finally!) many hours of frustration getting applications installed to Oculus Mobile.
Connect your Oculus Mobile to your PC via appropriate cable and turn it on.
Type adb devices in the command prompt to be sure your PC can in fact see the device.
While I can’t provide a crash course on cmd and dir commands, you will essentially need to path into the Android_ASTC folder of your project. I used the cd.. to get to the root of my C: then to where my project lives. I use the * shortcut to help save on typing.
From here you MUST type the name in exactly in order to install it. In this case it is: Install_MyProject-armv7-es2.bat
If this is the first time you install it, you will see a bunch of Java failed exceptions- it is trying to remove the previous installed application of the same name. You can ignore these. What you want to pay attention to is in the far lower left of the window- watch the percentage installation:I already have it on my ‘Quest so a successful install looks like this:
Unplug your headset and put it on. Under Library, look for Unknown Sources (Developer mode MUST be on in order to see Unknown Sources). Then on the right, click on MyProject. After a few seconds, you will be inside the side-loaded Virtual Reality template and application. Move around using A button for teleport on ‘Quest or trackpad on ‘Go. Palm trigger on ‘Quest can grab objects. Have fun!
I’ve used this template as a starting point to build other Oculus Mobile experiences.
There are a ton of steps to getting a creation onto Oculus Mobile. It has been a long and frustrating road for myself and many others. I believe Virtual Reality can be used in so many ways in both gaming and non-gaming applications to help people. Now that Oculus Mobile (especially Quest) is here, I am excited to see what myself and others can do with it.
I hope this blog post can reduce the time and effort and show people that they too can successfully build and deploy Unreal Engine 4 projects and apps to Oculus Mobile.
Thanks for reading!