Struggling to develop with the Oculus Quest? (it might not be you)

Struggling with the Oculus Quest with OVR Framework?

This is an opinion piece.  I’m tired of seeing companies not care about what they provide to developers, and then placing huge expectations on them to deliver back.

If you are struggling with the Oculus Quest, and the OVR Framework – I’m here to tell you that it is not you.  It is their framework that is the problem.

A bit about me, I’ve been a Unity dev for about 6 years now at various companies, and working in mobile for about 10 years… before founding our own AR/VR studio about 4 years ago.  During my career, I’ve launched over 200 mobile apps and games (yay) although mostly on BlackBerry 10.  The following is intended to be a guide, to help you work through the OVR framework (the Oculus SDK for Unity) and to help you see the issues that could cause problems for you later.
Without trying to word things carefully … this is one of the worst prepared VR frameworks I’ve ever used and I completely understand why some developers are struggling.  Oculus has set a high standard on developers building for the Oculus Quest but it doesn’t hold the same level of standards to their own tools and SDK’s.  The framework looks like it was assembled by interns without any sense of unified architecture.  It utilizes 3 different coding standards, has very no real documentation online, is sometimes documented internally, and has core functionality commented out with confusing comments left by the Oculus development team.  It is unprofessional, incomplete, and poorly documented.

However, don’t take this as a knock against the hardware.  The hardware is amazing.  The fault here is the internal development team building the OVR framework at Oculus.
First, I wanted to take a moment and say that we have been hammering away on our Oculus Quest for a few weeks now and used it for some tradeshows, multiplayer games, and client demos.  I’ve become intimate with the OVR framework, and rewritten a large portion to make it more usable.  I am very impressed with the hardware and the potential of the software.  But there are glaring holes and if you are struggling you need to know it might not be you – it might be (is) the framework.

Example of one of our Oculus Quest multiplayer games we’ve been working on:

My Experience

Over at Red Iron Labs, our team has done a LOT of VR content over the last 4 years from being funded by OSVR, to building for the Vive, Google Cardboard, Gear VR, Rift, and a bunch of VR headsets and frameworks that either haven’t seen the light of day or systems like the Cave VR system that is meant for industrial use.  Now, here is where as much as I love Oculus (and I do) I am going to come across a bit harder.  The framework has some serious issues, and if you are newer to Unity, these issues might just be why you are struggling.  I’m posting this here in the hopes that Oculus takes a moment to reflect on the OVR framework.  I find it very troubling how high of a bar they are setting for Developers to get approved for the Oculus Quest, when they aren’t holding their own framework to the same standard.  So, fair warning (and I know I’ll get some hate for this) I’m going to be hard on the OVR team.

Getting Started Documentation

Yes, there is almost no actual documentation on navigating the samples and installing the software for the Oculus Quest.  Oculus instead links you to the same tutorial instructions for the Oculus Rift, which are very much incomplete for the Rift, let alone ready for the Oculus Quest.

This is a perfect example of why professional companies need to hire professional writers.  Stop using developers to create online guides.  They don’t work and it isn’t their skill set.

Comparison:  This is a terrible getting started guide (Oculus Quest for Unity).  This is a perfect getting started guide (VRTK).  One is vague and provides no direction.  The other has comprehensive links and information walking through everything a user needs to begin working with a framework.

As a result, if you know Unity well and are willing to spend significant time walking through their source code, you will likely be able to figure it out on your own.  But these are unnecessary steps that they have placed on you (as a developer) instead of completing themselves.

Installing the Software

There are a bunch of different issues that can happen when you try to get everything up and running.  You are essentially using a desktop game engine, to convert the program to mobile, push it through a 3rd party service (ADB) and install it on a 3rd party Android based headset (Oculus Quest) with Oculus custom security software (that sometimes bugs out).  There are a lot of things that can go wrong in that chain and they provide no oversight or real documentation to help you through this.
There is a specific software stack you need to get it working correctly.
Note: Near as I can tell at the time of writing, because of the last requirement for Avatar support without errors in the Console, you will only be able to do the following on a Windows machine.
  • Install a tested version of Unity for OVR
    • I’ve been using Unity 2018.2.21.  Version .20 has known issues.  And anything Unity 2018.3 or higher is unusable with UI prefabs.
  • Install the latest Android SDK.
    • If you do not do this, you will likely be using the older Android SDK which includes a GUI (that Google no longer makes) which will generate the following error when you try and build with later versions of Unity.  Technically, this is a Unity issue, and even with the right SDK installed, their build scripts are only partially updated and Build will work (while Build & Run will fail).
  • Setup your Project to use the right version of Android.  This can be set in the Build settings for Android.
    • Failing this, you will see an error such as `UnityException: Required API level 26.`
  • (Recommended) Install the Oculus End-user SDK
    • Plan to work with Avatars?  You will get errors trying to do so with the Oculus Quest about a missing DLL, unless you install the SDK, and copy the respective DLL’s into your projects plugins folder.  Keep in mind, after doing so, you should ensure the DLL’s are set to Windows only.

Code Standards & Code Documentation

A professional software company has standards.  In fact, before a single line of code is written, a game or experience design document is generally drafted that includes the coding standards for the entire project.  Regardless, an architect or lead developer at a company is expected to maintain and oversee the code throughout the project.  One of the core goals, is to ensure that the standards are the same, and the documentation is standardized.  Oculus OVR framework appears to have no such standards.

If a framework is inconsistent in its wording, varies in how it operates, and provides no comprehensive guides to walk through the design – how can they set a high standard of expectations on developers using their framework?

Lack of Coding Standards and Consistency

The project uses 4 different coding standards.  The Unity/JavaScript camel case style C#, Hungarian notation, and proper C# and one that has no standard at all – often with script examples in the same folder.  This is unacceptable at any software company I’ve ever worked for.


  • Scripts such as \Oculus\Platform\Scripts\CallbackRunner.cs uses standard C# coding standards (i.e. public bool StartWithACapitalLetter = true;)
  • Scripts such as \Oculus\SampleFramework\SharedAssets\StartScene\Scripts\StartMenu.cs uses JavaScript coding standards (i.e. public bool startsWithALowerLetter = true;)
  • Scripts such as \Oculus\SampleFramework\Locomotion\Scripts\LocomotionSampleSupport.cs uses no coding standards at all (i.e. private bool everythingStartsLowerCase = true;)
  • Scripts such as Oculus\SampleFramework\Core\CustomHands\Scripts\Hand.cs uses Hungarian notation (i.e. private bool m_EverythingStartsWithM = true;)

Bad Coding Documentation

Generally speaking, the important part of documentation is consistency.  Most companies document “external code” or code being used by developers from other companies.  In some cases, Oculus did indeed appear to do that.  As the code appears rushed to incorporate the Oculus Quest features, however, that appears to not be the case.

The purpose to providing documentation, is to explain what you are doing, so other developers can learn from it.  If you use smart variable and function names, this can be minimized.  But the core purpose of a Sample Framework, is to educate and teach.  And interestingly enough, it is the Sample Framework that is undocumented (the code we should be learning from and rewriting) and it is the base OVR framework that is documented (the code we can’t change).  However, even then there are inconsistencies.


  • \Oculus\SampleFramework\Core\DistanceGrab\Scripts\DistanceGrabber.cs is properly documented
  • \Oculus\SampleFramework\Core\DistanceGrab\Scripts\DistanceGrabbable.cs, in the same folder, is not

All throughout the SDK, it goes back and forth.  With documentation created for trival things that don’t matter, and documentation missing on critical elements (such as teleporter tools).

Working Examples

Alright, let us pretend for a moment that coding standards and documentation doesn’t matter.  The basic question is – what examples work on the Oculus Quest, and do the work correctly?  The answer is a clear cut no idea, and no they don’t (because none of the examples are functionally complete, without serious bugs, and working properly).

Guiding Developers with Documentation

Oculus has a done an absolutely terrible job of guiding developers.  If you are lost, it is because they failed to walk you through their framework.

  • Here is an example of the Locomotion walk-through from Oculus that looks worse than a wordpress post.  It is a relatively short page, with two images, that contains the only teleportation and locomotion information in the entire manual (don’t worry I’ll go into more detail on why they implemented this entire thing wrong later – right now I’m focused on just the documentation page).
  • By comparison, here is the VRTK covering just one example script in their entire locomotion example set that is significantly more detailed, and provides an easy to read developer approach.

This is such a great example of providing poor documentation to developers, and something I plan to use at conferences as a talking piece going forward.

Functionality of Examples

All of this could be forgiven, as long as the examples are complete, and work.  However, this is still not the case.

By comparison, the VRTK provides many different clean scene demos with different teleportation methods.  SteamVR does very much the same.  OVR provides only a single Locomotion example.

Motion is by far the single most important subject for developers working with VR frameworks (especially for Rift developers – as contrary to what some of them believe it has long been a solved issue in the SteamVR world) and should have the most comprehensive set of examples available.  One thing we’ve all learned is that variations to locomotion is typically unnecessary and giving developers easy to use tools is critical if you want it to be consistent and successful on your platform.  By failing to do this, Oculus is forcing developers to self resolve locomotion, creating a fractured experience between applications (and going against their demand on developers to have unified control schemas).

Oculus Sample Framework – Locomotion Example

This is so very wrong.  This is unmanagable.  There is no fundamental reason to have all of these on a single object, if they want to convey different locomotion types – create different locomotion prefabs.  Or, if you really want to have this many variations of the same thing, created a custom Unity inspector.  More troubling is the terrible one-sentence documentation for many of these components (compared to the multi-page explanation for each component in the VRTK) and that significant portions of these example scripts don’t function and are actually commented out.

This is the wrong way to create a locomotion example.  And this absolutely should not be your only locomotion demonstration.  And this doesn’t take into consideration the asthetics issue (the example uses no audio, no animations, and just draws a giant white object on the floor – hardly something branded as beautiful as the StemaVR teleportation sample) and many of the scripts are copy/pasted code with large commented out sections (use inheritence).

There is also no way using these scripts to teleport and keep your current room rotation (which is what a user would expect) as the code contains bugs preventing a one-to-one teleportation rotation.  All of the example scripts, no matter what option is selected, will cause a random rotation of the user.  I believe the developers intended to provide a robo-recall style solution but it is coded incorrectly.  Instead it teleports room forward (not user forward) which is of course unknown to someone inside a VR headset.  This results in them almost always teleporting in a random location, even if they think they have a rotation selected.  This is the wrong way to do locomotion.  Further, I’ll expand on this later, the strange way they wrote the dependencies prevents decoupling of code elements and prevents things like easy network integration.

The only way to do proper SteamVR-like locomotion to prevent confusion and motion sickness, is to ignore the scripts and write your own.


SteamVR Locomotion Example

SteamVR for comparison is straightforward, it has a standard that developers use.  You go where you point, and you appear where you need.  It is a big overly simple (compared to the VRTK solution) but extremely fast to implement, relatively bug free and creates a uniform experience.

VRTK Locomotion Example

By far the VRTK has the most attractive system.  It is flexible, plug and play, and can be decoupled.  It is well documented, properly inherited, and flexible.
Unfortunately, this is just the locomotion example.  These issues are far worse in other areas and demonstrations.

To Be Continued

This covers the high level overview of some of the key issues in the Oculus OVR / Sample Framework.

In the next article, I’ll go into more detail about the bigger problems.  Such as

  • Incomplete code
  • Commented out code
  • Broken samples
  • Bad design
  • Confusing comments
  • Bad Unity standards and practices

There are many things wrong with this framework, and to cover it all has been taking me a week behind the scenes.  In this article, I’ve only just begun to scratch the surface on the issues (and this will probably get a hundred more edits).  I hope to have more time to actually sit down and show the bigger problems, solutions and walk you through making a better framework.  For us to create amazing demos on the Oculus Quest, we had to actually rewrite at least 20% of the framework and samples, so this will be a journey (not a small step).  And I hope to share more of my findings on that path.

I do honestly wish I had more time to narrow in on the issues, but bills need to be paid, and work needs to be done and fixing the Oculus framework for free isn’t high on my priority list (especially when we know how difficult it is to get their approval to launch for their platform) so as a caution it may be some time before I can post the second half of this article.