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.
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.
Example of one of our Oculus Quest multiplayer games we’ve been working on:
My Experience
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
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.
Examples:
- 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.
Examples:
- \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
VRTK Locomotion Example
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.
