by

Oculus Unity



-->

  1. Oculus Unity Development
  2. Oculus Unity Tutorial
  3. Oculus Unity Package
  4. Oculus Unity Controller Input

A Oculus Quest is required.

Oculus Audio Profiler for Windows. Oculus Lipsync Unity. Oculus OVRVoiceMod for Unity 5. To install Unity: Go to Unity Download page, click Download Unity Hub, and install it. On the Installs tab, click Add, select the Unity version from the list, and click Done. Unity Hub is an installation assistant that makes the installation process easy.

MRTK's support for the Oculus Quest comes via two different sources, Unity's XR pipeline and the Oculus Integration Unity package. The Oculus XRSDK Data Provider enables the useof both sources and must be used to use MRTK on the Oculus Quest.

The Unity's XR Pipeline enables the use of Oculus Touch controllers and head tracking with the Oculus Quest.This pipeline is the standard for developing XR applications in Unity 2019.3 and beyond. To use this pipeline, make sure that you using Unity 2019.3 or newer.

The Oculus Integration Unity package allows for the use of hand tracking with the Oculus Quest.This data provider does NOT use Unity's XR Pipeline or Legacy XR Pipeline, but because controllers and headtracking are handled by the Unity's XR Pipeline, the steps inSetting up project for the Oculus Quest must be followed to ensure that you are using the XR Pipeline and not the to-be-deprecated Legacy XR Pipeline.

Unity

Setting up project for the Oculus Quest

  1. Follow these steps to ensure that your project is ready to deploy on Oculus Quest.

  2. Ensure that developer mode is enabled on your device. Installing the Oculus ADB Drivers is optional.

Setting up the XR Pipeline for Oculus Quest

  1. Ensure that the Oculus XR Plugin is installed under Window --> Package Manager

  2. Make sure that the Oculus Plug-in Provider is included in your project by going to Edit --> Project Settings --> XR Plug-in Management --> Plug-in Providers

Setting up the Oculus Integration Unity package to enable handtracking

  1. Download and import Oculus Integration from the Unity Asset Store. The latest version tested towork is 20.0.0. Older versions can be found from this archive

  2. Navigate to Mixed Reality Toolkit > Utilities > Oculus > Integrate Oculus Integration Unity Modules. Doing this will update the asmdefs with definitions and references needed for therelevant Oculus Quest code to function. It will also update the csc file to filter out the obsolete warnings produced by the Oculus Integration assets. The MRTK repo contains a csc file that converts warnings to errors, this conversion halts the MRTK-Quest configuration process.

  3. In the imported Oculus folder (It should be found at Assets/Oculus), there is a scriptable object called OculusProjectConfig. In that config file, you need to set HandTrackingSupportto 'Controllers and Hands'.

Setting up the scene

  1. Create a new Unity scene or open a pre-existing scene like HandInteractionExamples
  2. Add MRTK to the scene by navigating to Mixed Reality Toolkit > Add to Scene and Configure

Using the Oculus XR SDK Data Provider

  1. Configure your profile to use the Oculus XR SDK Data Provider

    • If not intending to modify the configuration profiles

      • Change your profile to DefaultXRSDKConfigurationProfile and go to Build and deploy your project to Oculus Quest

    • Otherwise follow the following:

      • Select the MixedRealityToolkit game object in the hierarchy and select Copy and Customize to clone the default mixed reality profile.
      • Select the Input Configuration Profile
      • Select Clone in the input system profile to enable modification.
      • Open the Input Data Providers section, select Add Data Provider at the top, and new data provider will be added at the end of the list. Open the new data provider and set the Type to Microsoft.MixedReality.Toolkit.XRSDK.Oculus > OculusXRSDKDeviceManager

  2. The Oculus XR SDK Data Provider includes an OVR Camera Rig Prefab which automatically configures the project with an OVR Camera Rig and OVR Hands to properly route input. Manually adding an OVR Camera Rig to the scene will require manual configuration of settings and input.

Build and deploy your project to Oculus Quest

  1. Plug in your Oculus Quest via a USB 3.0 -> USB C cable

  2. Navigate to File > Build Settings

  3. Change the deployment to Android

  4. Ensure that the Oculus Quest is selected as the applicable run device

  5. Select Build and Run

    • You will likely encounter the following set of build errors when you select Build and Run the first time. You should be able to successfully deploy upon selecting Build and Run again.

  6. Accept the Allow USB Debugging prompt from inside the quest

  7. See your scene inside the Oculus Quest

Removing Oculus Integration from the Project

  1. Navigate to the Mixed Reality Toolkit > Oculus > Separate Oculus Integration Unity Modules
  2. Let Unity refresh as references in the Microsoft.MixedReality.Toolkit.Providers.Oculus.asmdef and other files are modified in this step
  3. Close Unity
  4. Close Visual Studio, if it's open
  5. Open File Explorer and navigate to the root of the MRTK Unity project
  6. Delete the UnityProjectName/Library directory
  7. Delete the UnityProjectName/Assets/Oculus directory
  8. Delete the UnityProjectName/Assets/Oculus.meta file
  9. Reopen Unity

Common errors

Quest not recognized by Unity

Make sure your Android paths are properly configured. If you continue to encounter problems, follow this guide

Edit > Preferences > External Tools > Android

In this tutorial, we’ll demonstrate how to setup your Oculus Quest with Unity for development: from putting your device into developer mode, to setting up your Quest controllers.

We’ll be developing our Oculus Quest in OpenVR because of its cross-platform capabilities.

Skip to the Technical Steps

First up, you’ll have to download the Oculus app onto your phone. You’ll be able to manage all Oculus devices through this app.


Once the app is installed, turn on your Quest. In your Oculus app, select “Settings” in the lower right corner.

Select your Oculus Quest from the list. If it isn’t appearing, try restarting your Quest.

In the menu that appears when you select your Quest, select “Other Settings.” Click the slider to activate Developer Mode.

At this point you’ll be prompted to register for a developer certificate with Oculus. If you already have one, you can move to the next step!

You’ll be using Android SDK and related tools in Unity, so we’ll have to make sure you have these plugins installed.


Download Android Studio from their website. Open Android Studio, go to your top menu to access “File,” then “Settings” to open your SDK Manager.

Download and install:

  • Android 4.4 (SDK19)
  • Android 7.1 (SDK 25)
  • SDK Tools (In the “Android SDK Tools” tab)
  • SDK - Platform Tools

If you haven’t installed Unity yet, let’s get that process started. It’s free and available on Unity’s website here.


When installing Unity, make sure you install the Android Build Support with it.
To develop for Oculus Quest, you’ll want the 2017.4 version of Unity or higher.

Let’s open up Unity and create a new project. Name it something unique that you’ll remember. Change your Template to “3D”. Lastly choose the folder location where you’d like to save this project.


Oculus tries what it can to make building for its devices easy on the developers. The Oculus plugin is compatible for the Quest and all other Oculus devices. Plus it’s free, bonus!


To download and/or import the plugin, go to Unity’s Asset Store along the finder bar at the top of your screen. Once the Asset Store window opens, search for “Oculus Integration.” Download this plugin, or import it into your project if you already have it downloaded.

Your Unity project may ask if you want to update the Oculus Plugin Utilities. Select “Yes” and “Restart”. Sit back and relax while your computer does its thing.


Head back up to your finder bar at the top of the screen and mouse over “Window” then click on “Package Manager” and select the tab “All.” This is a long list of available packages to install in your project. The two we’re looking for are “Open VR” and “XR Legacy Input Handlers.” Select them to install, and close the Package Manager.


Note that “XR Legacy Input Handlers” may not be listed if you’re using an older version of Unity. If this is the case, the Input Handlers are automatically installed.

You’re doing great! We’ve downloaded and installed all the tools you need to develop for Oculus Quest. Now we need to make sure they’re configured to work with your project.

In Unity, go to your top menu, hover over File, and click on “Build Settings…”

The Build Settings window appears. If there are any settings listed in the “Scenes in Build” area, select them and delete them. We want to start from scratch.

Click on the “Add Open Scenes” button and add the scene you currently have open. This may take a minute or two.

In the Platform menu within “Build Settings” click on “Android” and select “Switch Platform.” While doing this, make sure your Texture Compression is set to “ASTC.”


Next, Click on “Player Settings” on the lower left-hand side of the window. This opens another window on the far right off the screen. In “Player Settings,” you’ll want to change:
  • Company Name
  • Product Name

Scroll down and unfold the “Other Settings” section. In the “Identification” section, change Minimum API Level to 4.4 KitKat. Confirm your Package Name is along the lines of “com.company name.product name”
Scroll down and unfold the “XR Settings” section. Confirm that “Virtual Reality Supported” is checked.
Lastly, in the “Virtual Reality SDKs” section, click on the little “+” and select “Oculus.” Then click “Build” on the bottom right-hand side of your Build Settings window. You’re now ready to start building!

Note: Some users get an error at this point. If this is the case for you, go back into “Other Settings” and into the “Graphics API” list. Remove “Vulcan” and your error should be resolved.

Download our 10-week XR Development with Unity Course Syllabus

We’re going to set up a couple of spheres to represent your controllers ingame. You can download any asset from Unity’s Asset Store to represent your controllers and hands, but for simplicity in this tutorial we’ll be using spheres.

Head over to your Hierarchy on the left hand side. Right-click to add a GameObject, and let’s add a sphere.

On the right hand side is your Inspector. When selecting your new Sphere, head to the Inspector and set the scale of your sphere to 0.1 in X, Y, and Z fields (this is 0.1 meter).

Right-click in the Inspector to add a Tracked Pose Driver component to the sphere. (This is why we needed the XR Legacy Input Handler package). In this component, set your “device” to Generic XR Controller.

Add another component, this time a Rigid Body Component to your sphere. Enable the “isKinematic” property, and disable “Use Gravity.”

Duplicate this sphere and change your “Pose Source” in the Tracked Pose Driver to “Right Controller”. Double check that the other sphere’s “Pose Source” is set to “Left Controller.”


Next, set the position of your Main Camera and spheres to 0, 0, 0 in the Inspector. Great!

Let’s add a Cube to the scene so we have something to see and interact with while in game.

Right-click in the Hierarchy tab to create a new GameObject and select a Cube.

Set the position of the Cube to 0, 0, 1 so it will appear 1 meter in front of you.

In the Cube’s Inspector tab, add a RigidBody component, and make sure to disable “Use Gravity” so the Cube floats in front of you.


Save your scene by going to your top menu, hovering over File and selecting Save.

We’re very close to being done!

Connect your Oculus Quest to your computer through a USB cable. Put on the Quest and enable USB debugging for this computer.

Oculus Unity Development

Back in Unity, head back up to the top menu to File and “Build Settings…” Open the Build Settings window and click on “Build and Run” in the lower right-hand corner. Alternatively you can go to the top of the Unity menu, select Oculus, and access Build and Run from there.

You can then choose a name for your APK (Android Package Kit) and select where to save it. We generally recommend creating a new folder labeled “Builds” for easy organization.


After saving, Unity will have saved your application onto your USB-connected Quest. You can now disconnect the Quest from your computer and launch the project.

Oculus Unity Tutorial

To find your project while wearing the Oculus Quest, go to your Libraries on the left-hand menu, select Unknown Sources, and your project should be listed there.

Building for the Oculus Quest is an ambitious endeavour, good job! It’s a great device to get started with.

Now that you’re setup for Oculus Quest development, you’re ready to get building more advanced projects. Check out our programming guide for tips, advice, and resources to developing a VR app.

Oculus Unity Package

If you’re looking for guidance in Unity development, we can help with that. Through our 10-week course and one-on-one training, we’ll take you from idea to prototype to finished app. Download our syllabus to learn more about what we can teach you!


Technical Steps:

Oculus Unity Controller Input

  1. Unlock Developer Mode on Oculus Quest
    1. Download Oculus App onto your phone
    2. Turn on Oculus Quest
    3. Select Oculus App settings
    4. Select your Quest from the list of devices
    5. Select Other Settings
    6. Select Slider to activate Developer Mode
    7. Register for Developer Certificate with Oculus if you haven't done so already</li
  2. Install Android Tools
    1. Download Android Studio
    2. Open Android Studio and Select File > Settings > Android SDK
    3. Within the Package Manager, download and install:
      1. Android 4.4 (SDK19)
      2. Android 7.1 (SDK25)
      3. SDK Tools (within the SDK Tools tab)
      4. SDK - Platform Tools (within the SDK Tools tab)
  3. Install and run Unity
    1. Download Unity with version 2017.4 or newer
      1. Ensure Android Build Support selected to download as well
  4. Create new Unity project
    1. Go to Unity's Asset Store and search 'Oculus Integration'
    2. Download, Import, or Update the plugin, depending if you've accessed it before
    3. If prompted, update Oculus Plugin Utilities and restart Unity
  5. Install OpenVR and XR Legacy Input packages
    1. In Unity's top menu, go to Window > Package Manager
    2. Select OpenVR and XR Legacy Input Handlers
    3. Close Package Manager
    4. Note: If using an older version of Unity, the Input Handlers are built in and will not need to be manually installed
  6. Set Project's Build Settings
    1. Go to File > Build Settings...
    2. Delete any scenes listed in the 'Scenes in Build' area
    3. Click 'Add Open Scenes' to add current scene to Build
    4. Change Platform to 'Android' and set Texture Compression to 'ASTC'
    5. Click on 'Player Settings' and change:
      1. Company Name
      2. Product Name
    6. In Player Settings, go to:
      1. Other Settings > Identification > Change Minimum API Level to 4.4 KitKat
      2. Under Identification, confirm your Package Name is along the lines of com.company name.product name
      3. XR Settings and confirm 'Virtual Reality Supported' is enabled
      4. Virtual Reality SDKs section, click on '+' and add 'Oculus'
    8. Click 'Build' in Build Settings
    9. If you receive error message, go to Player Settings > Other Settings > Graphics API > Remove Vulcan
  7. Setup Oculus Quest Controllers
    1. To represent controllers by spheres:
      1. Add 3D Object Sphere
      2. Change Sphere scale to 0.1 in X, Y, and Z
      3. Add Tracked Pose Driver component, set Device to 'Generic XR Controller'
      4. Add RigidBody component, enable 'isKinematic' and disable 'Use Gravity'
      5. Duplicate Sphere and change Pose Source in Tracked Pose Driver to 'Right Controller.' Double check the other Sphere's Pose Source is set to 'Left Controller'
    2. Change Spheres and Main Camera position to 0, 0, 0 in Inspector
  8. Setup VR scene
    1. Add 3D Object Cube
    2. Set Cube position to 0, 0, 1
    3. Add RigidBody Component and disable 'Use Gravity'
    4. Save scene
  9. Launch Unity Project onto Oculus Quest
    1. Connect Quest to your computer via USB
    2. Put on Quest and enable USB debugging for this computer
    3. In Unity, go to File > Build Settings... > Build & Run
    4. Choose name for APK; Create new 'Builds' folder and save APK within
    5. Once Unity has finished deploying project onto Quest, disconnect Quest and put on
    6. Access your project from Quest Main Menu > Libraries > Unknown Sources