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.
Update: We’ve published a follow up article that goes into developing a holographic UI in VR for Unity. You can read it here.
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+
- Go to Edit > Project Settings.
- Click on ‘XR Plugin Management’ in the left panel and click ‘Install XR Plugin Management’.
- 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:
- Go to Edit > Project Settings > Player > XR Settings and check ‘Virtual Reality Supported‘.
- In addition, ensure ‘Oculus’ appears in the list as shown below. Otherwise, you may add it using the ‘plus’ symbol.
Oculus integration
- Go to the ‘Asset Store’ tab and search for ‘Oculus Integration’.
- Click ‘Download’ to download the package.
- After the download is finished, click ‘Import’ to import it to your project.
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:
- 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:
- Select your ‘Scene‘ and remove ‘Sample Scene‘.
- In the Platform section, select ‘Android’.
- In the Texture Compression field select ‘ASTC’ (this provides the best balance between quality and file size).
- 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: select ‘Low 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:
- Through Unity by using the Oculus Link cable (for Unity older versions: Go to Oculus > OVR Build > OVR Build APK & Run).
- Through Oculus Hub over Wi-fi and without using a cable.
The next step: Holographic UI in VR
You’re now ready for the next step, creating a holographic UI in VR for Unity. Learn how to do gestures, teleporting and setting up a basic UI. Read our next article in this series to learn more: developing a holographic UI in VR for Unity.
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:
- Enable Hand Tracking.
- Confirm HandTracking Support to Controllers and Hands.
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:
- 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.
- 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:
- Enable Developer Mode, if disabled.
- Oculus Guidelines.
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:
