Setting up your Oculus within Unity to develop VR applications

Contemporary technology and the progressing complexity of nowadays product development creates a growing necessity for tools that assist engineers in manufacturing. Such tools are commonly perplexing and require attention to detail. Technology like Virtual Reality headsets and associated software are of increasing importance since their usage has exploded in recent years, as means of innovative experiences and applications in multiple sectors.

While developing Virtual Reality applications or prototypes, engineers frequently choose Unity3D, as Unity provides cutting-edge tools and libraries to become creative and productive in VR. However, there are a number of set-up steps and configurations to follow before being able to successfully work on VR environments using Oculus headsets. Missing a specific configuration or step sometimes leads to common pitfalls that could block you from being able to debug your app in Unity.

This article is aiming to guide you through the basic setup steps that you need to develop and build Hand-Tracking VR applications.

Table of contents:

Let’s get started!


Required applications

In order to create apps for Oculus hardware, you’ll need to have the following products:

Hardware

  • Oculus headset: Quest, Quest2, Rift, Go.
  • A high-quality USB cable that is used for Oculus Link.
  • Laptop/Desktop computer meeting these requirements.
  • Smartphone compatible with Oculus App, according to the headset you use: Quest, Quest2 and Go.

Software

  • Oculus PC App.
  • Unity Hub.
  • Unity latest version.
  • Oculus Integration package for Unity.
  • Latest software version on Oculus (Oculus headset -> Settings -> About -> Software version -> Download latest version).

Facebook Account

According to Oculus Guidelines (as Oculus is owned by Facebook), there are some account requirements according to your device:

  • Quest 2 requires everyone to use a Facebook account to log in.
  • For previous generation Oculus devices:
    • New users need to log in with a Facebook account.
    • Existing Oculus users will have the option to merge their accounts with the Facebook one. Users can also choose not to merge and continue in Oculus for 2 more years.
    • Test users who use Oculus exclusively for development purposes can set up a Test-User Account.

Connecting the headset

Now we will explain in three steps how to connect the headset.

Step one

The initial step, having downloaded the Oculus app on your phone, is to enable the Developer mode as such: go to Settings > More Settings > Developer Mode and toggle the ‘Developer Mode’ on.

Step two

Now you can connect the headset to your PC, using the USB-C cable. This action will cause a pop-up window within your Oculus:

Check the ‘Always allow’ checkbox and click ‘ok’. This will enable the connection between the headset and your computer in debugging mode (testing the app, while developing within Unity).

Step three

In order for the headset to recognize and track your hands successfully, verify that Hand Tracking’ is enabled on the device. To do so, while wearing the headset, navigate to Settings > Device > Toggle the “Hand Tracking” feature.

Your headset is set up for development! Now, let’s move onto setting up Unity.


Setting up Unity

Having installed Unity from Unity Hub, make sure that all the necessary Android SDK/NDK/JDK has been installed (preferably keep Android versions: 4.4KitKat, 7.1Nougat, 10.0 latest). The Unity settings to configure are project-specific, based on the Unity version you are using and the app you are trying to develop. 

Step 1: creating the project

You can now go ahead and create your first VR project:

Selecting URP will assist in maintaining optimal performance for your Android build.

Step 2: download packages

Once you’ve created the Unity project, there are some required packages you’ll have to download from Unity Package Manager.

Download XR Plugin Management

For Unity 2019.4+

  1. Go to Edit > Project Settings.
  2. Click on ‘XR Plugin Management’ in the left panel and click ‘Install XR Plugin Management’.
  3. To enable VR support in Unity for Oculus, check the “Oculus” checkbox:

For Unity 2019.3 or older

In case you are using an older version of Unity (< 2019.3), to enable Oculus VR Support:

  1. Go to Edit > Project Settings > Player > XR Settings and checkVirtual Reality Supported‘.
  2. In addition, ensure ‘Oculus’ appears in the list as shown below. Otherwise, you may add it using the ‘plus’ symbol.

Oculus integration

  1. Go to the ‘Asset Store’ tab and search for ‘Oculus Integration’.
  2. Click ‘Download’ to download the package.
  3. After the download is finished, click ‘Import’ to import it to your project.
  4. Before importing, a prompt window will appear where you may choose which components to import from the package. Depending on what you are building, select the preferred components and click ‘Import‘. This process may take a while.

After the import is done, it is wise to restart Unity in order to make sure everything will work smoothly.

Additionally, to guarantee the package is up to date, after Unity restarts:

  1. Go to Oculus Tab > Oculus > Tools > Update OVR Utilities Plugin

Step 3: build Configurations

Using Unity, there are some configuration settings that will facilitate your comprehension of view and interaction in the VR environment.

Build Settings

Go to File > Build Settings:

  1. Select your ‘Scene‘ and remove ‘Sample Scene‘.
  2. In the Platform section, select ‘Android’.
    1. In the Texture Compression field select ‘ASTC’ (this provides the best balance between quality and file size).
    2. Press ‘Switch Platform’. 

Player Settings

Go to Edit > Project Settings > Player:

Other Settings

  • Color Space: Select ‘Gamma’ (this will take a while too, as every texture needs to be re-compressed)

When using Linear space the colors supplied to shaders within your scene will brighten linearly as light intensities increase. Hence, lighting in your scene will look more realistic. However, if your app is not focusing on the style, Gamma color space will give you better performance.

  • Minimum API Level: select level according to minimum API level you want to support.

Minimum Android version (API level) required to run the application on your phone. 

Confirm whether your phone appears in the detected devices from the Build Settings.

  • Target API Level: Select “Automatic”.

Configuration

  • Scripting Backend: Select “IL2CPP”.

With IL2CPP Unity converts IL code from scripts and assemblies to C++, before creating a native binary file (.exe, apk, .xap, for example) for your chosen platform (source). Using this option will make your app run faster, but the building process will take longer.

  • API Compatibility level: select ‘.NET 4.x’.
  • Target Architecture: select ‘ARM64′.

XR Settings (for Unity older versions)

Set ‘Stereo Rendering Mode’ to ‘Single Pass’. With Single Pass mode, all draw calls are rendered once for the left eye and then duplicated for the right, instead of doing the process for each eye separately. This will optimize rendering. For more information, see Unity documentation.

Graphics Settings

Go to Edit > Project Settings > Graphics:

In Scriptable RenderLoop Settings: selectLow Quality Render Pipeline Asset‘ and drag it. This will allow better performance, as Low quality removes the shadows and high-quality render settings.

Within the asset, you can modify the ‘Anti Aliasing‘ settings, which should generally be set to ‘4x Multi Sampling‘. If this has a large enough impact on performance, using 2x is also acceptable.

In general:

  • Be sure to have Oculus Link Enabled for debugging mode.

Step 4: Scene & Script Configurations

Hang in there, we’re almost finished! Now, within the Unity Editor, we can do the following to enable Hand Tracking experience:

New Scene: 

  • Create a new scene.
  • Remove Main Camera (we don’t need it, as the player “sees” through the OVRCameraRig).
  • Add OVRCameraRig.prefab.
  • Add both prefabs of the hands: OVRCustomHand.prefab.

OVRManager.cs  

This script is attached to OVRCameraRig.prefab

  • Uncheck ‘Use Recommended MSAA Level’ (only in case you receive multiple warnings. If this setting is enabled, it will override the Scriptable RenderLoop .asset file Anti-Aliasing settings).
  • Tracking Origin Type: ‘Floor Level’ (for XR devices that support 6 degrees of freedom tracking, this is the ability to move around your play area).
  • Quest Option -> HandTracking Support: ‘Controller and Hands’ (enables controllers and hand tracking simultaneously).

Select OVRCustomHand.prefab:

OVRCustomSkeleton.cs

Check:Update Root Pose’, ‘Update Root Scale’ and ‘Apply Bone Translation’ (hands reference to scene global space instead of tracking space).


Finally, it’s time to build!

There are few ways to perform a build. Go to Unity’s Build Settings > Build/Build And Run: 

  1. Through Unity by using the Oculus Link cable (for Unity older versions: Go to Oculus > OVR Build > OVR Build APK & Run).
  2. Through Oculus Hub over Wi-fi and without using a cable.

Common Pitfalls

You are all set up, but you may have experienced some troubles along the road. Let’s discuss some common pitfalls and how to solve them.

Pink Hands

Issue: My hands are pink/magenta (as if missing shader color) and stuck to the floor.

Problem: Hand Tracking is disabled in your headset.

Solution:

Warnings

Issue: Multiple warnings every frame such as: “The current MSAA level is 0, but the recommended MSAA level is 4. Switching to the recommended level”.

Problem: Checkbox “Use Recommended MSAA Level” in OVRManager.cs settings is checked.

Solution: Uncheck the box.

If your script is instantiated during runtime, you may accomplish this programmatically using the following command:

OVRManager.instance.useRecommendedMSAALevel = false;

Weird Movement Scale

Issue: Moving within the VR environment is not scaled accordingly with real movement. I have to move much further in reality, to go where I need to in VR.

Problem: Hands are referencing real tracking space.

Solution: Check the corresponding configuration in your Hands prefabs from OVRCustomSkeleton.cs.

Error on Build

Issue: “Error: Android SDK not found or invalid. Please fix it in Preferences > External tools”.

Problem: SDK path is not properly configured during Android installation. 

Solution: One way to install Android SDK is from UnityHub > Installs > Add Modules and ensure the Android modules and JD are checked.

Another way is to install it through Android Studio and then perform the following steps: 

  1. Go to Edit > Preferences > External Tools and set the paths of JDK/SDK and NDK accordingly. Android Studio should install the Android SDK to your user’s AppData/Local/Android/Sdk folder, and the Android NDK to your user’s AppData/Local/Android/Sdk/ndk/<version number> folder.
  2. Locate your installed Java SDK and use that version in your settings.  If you still receive JDK incompatibility versions:
    • Download the necessary JDK version.
    • Go to Control Panel > System > Advanced System Settings > Advanced > Environment Variables and add the corresponding path of the required Java JDK for the variable “JAVA_HOME”.

Error on Build

Issue: “Error: No ADB Devices connected. Cannot perform OVR Build and Run”.

Problem: Your Oculus headset is not recognized by Unity, because its drivers have not been properly installed on your computer.

Solution:


tim-laning

That’s it! We hope this guide helped you to develop and build Hand-Tracking VR applications. Do you still need help? We’re here to help. Contact Tim Laning via:

 

Share this post on:
TwitterLinkedInFacebook