Unity Sample Framework

The Oculus Unity Sample Framework provides sample scenes and guidelines for common VR-specific features such as hand presence with Oculus Touch, crosshairs, driving, hybrid mono rendering, and video rendering to a 2D textured quad.

The Unity Sample Framework can guide developers in producing reliable, comfortable applications and avoiding common mistakes. The assets and scripts included with the Sample Framework may be reused in your applications per the terms of our SDK 3.4.1 license. Note that some folders of the Sample Framework include a more permissive BSD license - this license supersedes the SDK 3.4.1 license in folders in which it occurs. See LICENSE.txt in the relevant folders for additional details.

The Unity Sample Framework is available as a Unity package for developers who wish to examine how the sample scenes were implemented, and as executable binaries for Rift, Oculus Go, and Gear VR for developers to explore the sample scenes entirely in VR.

The Sample Framework Unity package is available from the Unity Asset Store here. The executable Rift and Mobile applications are available by searching for Oculus Sample Framework in the Oculus Store.

Sample Framework UI Scene

The Unity Sample Framework works on all currently-supported versions of Unity. Please check Compatibility and Requirements for supported versions.

Sample Scenes

In the Unity project, the following scenes are found in /Assets/SampleScenes:

Scene

Directory

Concept Illustrated

Multiple Cameras

Cameras/

Switching between cameras in a scene.

Crosshairs

First Person/Crosshairs/

Using crosshairs to aim a weapon in VR and different configuration options.

Mirror

First Person/Mirror/

A simple mirror effect.

Outdoor Motion

First Person/

Basic forms of movement, and the effects a variety of design choices may have on comfort.

Scale

First Person/

How various scale factors interact.

Stairs

First Person/Stairs/

Factors affecting comfort in first-person stairs movement.

Teleport

First Person/Locomotion/Teleport/

A teleportation locomotion scene that reduces the risk of discomfort.

TeleportAvatar

First Person/Locomotion2/TeleportAvatar/

A teleportation scene that supports switching between any combination of teleports and linear motion at run time.

GuardianBoundarySystem

Guardian Boundary System/

Illustrates use of OVRBoundary API to interact with Guardian System Outer Boundary and Play Area.

AvatarWithGrab

Hands/

Uses the Unity Avatar SDK and the scripts OVRGrabber and OVRGrabbable to illustrate hands presence with Touch. Pick up and throw blocks from a table using the Touch grip buttons. This sample requires importing the Oculus Avatar SDK.

CustomControllers

Hands/

A simple sample displaying tracked Touch models in a scene.

CustomHands

Hands/

Uses low-resolution custom hand models and the scripts OVRGrabber and OVRGrabbable to illustrate hands presence with Touch. Pick up and throw blocks from a table using the Touch grip buttons. May be used as a reference for implementing your own hand models.

Distance Grab

Hands/

Illustrates selecting and grabbing distant objects with hand models using Touch. For more information, see Distance Grab Sample on our Developer Blog.

Input Tester

Input/Input Tester/

This scene assists with testing input devices, displaying axis values in real time.

Keyboard

Input/Keyboard/

A virtual keyboard.

InputFocus

InputFocus/

Illustrates typical handling for loss of Input Focus, such as when a Dash overlay is present. The application is paused, muted, and tracked controllers are hidden.

MRCTest

MixedRealityCapture/

A simple scene with mixed reality capture enabled.

Splash Screen

OVRHarness/Scenes/Loading.unity*

Splash screen modal that supports custom images and content.

Movie Player

Rendering/Movie Player/

Video rendering to a 2D textured quad using the Android Media Surface Plugin. Source for the plugin ships with the Mobile SDK in \VrAppSupport\MediaSurfacePlugin.

Surface Detail

Rendering/Surface Detail/

Different ways to create surface detail with normal, specular, parallax, and displacement mapping.

OverlayUIDemo

UI/Overlay/

Demonstrates creating a UI with a VR Compositor Layer to improve image quality and anti-aliasing. Includes a quad overlay for , and a quad and a cylinder overlay for mobile.

Pointers

UI/Pointers/

How UI elements can be embedded in a scene and interact with different gaze controllers.

Pointers - Gaze Click

UI/Pointers - Gaze Click/

An extension of the Pointers scene, with gaze selection.

Note: * The Splash Screen sample is found in a different location from the other samples listed in this table.

A Note on Comfort

These samples are intended to be tools for exploring design ideas in VR, and should not necessarily be construed as design recommendations. Some sample scenes in the Sample Framework allow you to set some parameters to values that will reliably cause discomfort in most users. They are offered to give developers an opportunity to find out precisely how much is too much in certain scenarios.

It is important to play test your game on a range of players throughout development to ensure your game is a comfortable experience. We have provided in-game warnings to alert you to potentially uncomfortable scenes.

Downloading and Installation

The Unity Sample Framework package can be downloaded here or by searching for Oculus Sample Framework in the Asset Store tab of the Unity Editor. The executable Rift and Mobile applications are available by searching for Oculus Sample Framework in the Oculus Store.

To open the project in Unity Editor:

  1. Verify that you have installed a recommended version of Unity (see Compatibility and Requirements for up-to-date information).
  2. Launch the Unity Editor and create a new project.
  3. Download and import the Unity Sample Framework project from here or the Asset Store tab of the Unity Editor.

Building the Unity Project

This is only necessary if you want to experiment with the project, as the executable Rift and Mobile applications available for free download in the Oculus Store are simply builds of the Unity project.

To build the Unity Project for Rift:

Note: You will need to enable running applications from unknown sources in the Oculus app settings. Launch the Oculus app, select Settings > General, and toggle Unknown Sources on to allow. You may wish to disable this setting after use for security reasons.
  1. Import the Sample Framework project as described above.
  2. From the menu bar in the Unity Editor, select OVR > Samples Build Config > Configure Rift Build.
  3. Build and run the project normally.

To build the Unity Project for Mobile:

  1. Import the Sample Framework project as described above.
  2. From Editor menu bar, select OVR > Samples Build Config > Configure Gear VR Build.
  3. Ensure the project contains an Oculus signature file and that you have an Android keystore configured. See Application Signing in our Mobile SDK documentation for more details.
  4. Sample Framework Android builds use a custom manifest and are not visible from Applications, and cannot be launched from Oculus Home or the Android Application Launcher. To launch:
    1. Install the APK to your phone.
    2. Open Settings > Applications > Application Manager > Gear VR Service.
    3. Select Storage.
    4. Select Manage Storage.
    5. Toggle Add icon to app list to On.
    6. Close Settings.
    7. Open Apps.
    8. Select Gear VR Service.
    9. Select Oculus Sample Framework to launch.

Exploring the Sample Framework in VR

Sample scenes are browsed and controlled with a simple UI which provides in-app explanatory notes. Parameter controls allow users to adjust settings, providing an immediate, direct experience of the impact of different design decisions. The Sample Framework control panel itself is an example of in-VR control and navigation, and may be used as a model for your own applications.

Navigation

Launch the Sample Framework on Rift, Oculus Go, or Gear VR to load the startup scene. You will see the Inspector, a three-pane interface providing controls for scene settings, documentation, and navigation controls for browsing to other scenes. Making selections on the top-level menu on the left panel changes the content of the other two panels. The center panel is a contextual menu, and the right panel displays notes and instructions for the current scene.

Sample Framework Inspector

To launch a scene from the center panel, select and click the scene with your controller or gaze at the scene name and tap the Gear VR touchpad.

Some scenes are grouped into folders (displayed as buttons). When browsing from a folder, select “..” to navigate one level up in the scene hierarchy.