Unity Integration

1.31.0 | Published 2018-11-15

Oculus Integration for Unity - 1.31.0

The Oculus Integration for Unity is available in the Unity Asset Store. Download the package from the Oculus Integration page, or by searching for Oculus Unity Integration in the Asset Store tab of the Unity Editor.

Please see Compatibility and Version Requirements for important known Unity issues and support information.

The Oculus Utilities for Unity package includes includes scripts, prefabs, and other resources to supplement Unity’s built-in support. The package includes an interface for controlling VR camera behavior, a first-person control prefab, a unified input API for controllers, advanced rendering features, object-grabbing and haptics scripts for Touch, debugging tools, and more.

New Features

  • Added cross-platform development support to the Unity Integration. Starting with 1.31 developers can use the Oculus Integration and Utilities to develop VR apps for multiple platforms. Please see the Unity Cross-Platform Development guide for more information.
  • Added SetColorScaleAndOffset() to OVRManager. Use SetColorScaleAndOffset() to apply post-rendering effects to the scene. Additional information can be found in the OVRManager guide.

Integration Changes

  • 1.31 contains changes to the structure of the Oculus Integration package and includes new assembly definition files (*.asmdef). These files will package the Oculus Utilities scripts into 3 DLLs: Oculus.VR.dll, Oculus.VR.Editor.dll and Oculus.VR.Scripts.Editor.dll. Developers who use their own assembly definitions will need to add references to Oculus.VR.*. Information about how Unity uses assembly definition files can be found in Unity's Script compilation and assembly definition files page.
  • The Unity Integration 1.31 contains the following changes to the Oculus Integration for Unity package:
    • Update the Oculus Utilities to 1.31
    • Update the Platform SDK to 1.31
    • Update the Avatar SDK to 1.31
    • Update the Audio Spatializer to 1.31

Bug Fixes

  • Added support for Mobile sRGB. This fixes a conversion issue where on Mobile and when the rendering Color Space was set to 'Linear', the resulting scene was overly dark from an improper linear to gamma conversion.

Angular Velocity and Acceleration in the Unity Integration 1.31

Angular velocity and angular acceleration values are reported in 1.31 in degrees, not radians.

Import instructions

To import Oculus Integration for Unity into your project, perform the following steps:

1. Manually Delete any Previous Versions

If you have previously imported another version of the Integration or Utilities package into your project, delete the following Oculus content from your Unity project folder before importing a new version:

Note: Be sure to close the Unity Editor before proceeding.

Files to delete in Utilities version 1.22 or earlier

Folder (1.22 or earlier)

Content to Delete

Assets/Plugins

Oculus.*

OVR.*

Assets/Plugins/Android/

*Oculus*

AndroidManifest.xml

*vrapi*

*vrlib*

*vrplatlib*

Assets/Plugins/x86/

Oculus.*

OVR.*

Assets/Plugins/x86_64/

Oculus.*

OVR.*

Files to delete in Utilities versions after 1.22

Folder (1.22 or earlier)

Content to Delete

Assets/Plugins

Oculus.*

OVR.*

Assets/Plugins/Android/

*Oculus*

AndroidManifest.xml

*vrapi*

*vrlib*

*vrplatlib*

Assets/Plugins/x86/

Oculus.*

OVR.*

Assets/Plugins/x86_64/

Oculus.*

OVR.*

2. Open or Create a Unity Project

If you're already working in a Unity project, save your work before importing. Otherwise, create a new project:

  1. From the Unity menu, select File > New Project.
  2. Click the Browse button and select the folder where the Unity project will be located.
  3. Make sure that the Setup defaults for: field is set to 3D.
  4. Click the Create button.

3. Import the Unity Package

The latest Oculus Integration for Unity is available in the Unity Asset Store. Download the package from the Oculus Integration page, or by searching for Oculus Unity Integration in the Asset Store tab of the Unity Editor.

When the Importing package dialog opens, leave all of the boxes checked and select Import.

4. Update OVRPlugin (Optional)

The Oculus OVRPlugin provides built-in Editor support and some additional features. The latest version is included in the Utilities for Unity package, and if it is later than the detected version in the Editor, you're given the option to automatically update your project. We always recommend using the latest version.

Version-Specific Known Issues

This section details known issues with specific versions of Unity.

Unity Version

Known Issues

2018.2

All Unity 2018.2 versions

  • (Mobile) You'll need to either switch the AndroidBuildSystem to internal or export a Gradle project and modify the SigningConfig in the build.gradle file to include v1SigningEnabled=true, v2SigningEnabled=false.

2017.4

2017.3

All Unity 2017.4.1 versions

All Unity 2017.3 versions

  • (Mobile) You'll need to either switch the AndroidBuildSystem to internal or export a Gradle project and modify the SigningConfig in the build.gradle file to include v1SigningEnabled=true, v2SigningEnabled=false.

2017.2

Unity versions 2017.2.0f3-2017.2.0p2

  • The Unity engine uses projection matrix calculations that are at variance with the Oculus SDK, causing VR scenes to have the wrong parallax, which may cause discomfort.

2017.1

Unity versions 2017.1-2017.1.2p1

  • The Unity engine uses projection matrix calculations that are at variance with the Oculus SDK, causing VR scenes to have the wrong parallax, which may cause discomfort.

Unity 2017.1.0f2 and later

  • When using Adaptive Resolution, you might experience some slightly pixel shaking when resolution is changing, this is a known issue, we are working with Unity to resolve it.

5.6

Unity versions 5.6 and later

  • If you have updated your OVRPlugin version from Utilities, you may see a spurious error message when the Editor first launches saying “Multiple plugins with the same name 'ovrplugin'”. Please disregard.

Unity 5.6.0f2 and Unity 5.6.0p1

  • Gear VR applications built with these versions crash immediately upon launch.

Unity versions 5.6.0p2-5.6.0p3

  • Two graphics driver issues affect mobile applications with Single Pass Stereo rendering enabled using some S8 or S8+ phones. They can occur when Standard Shader Quality is set to low, or when you are using tree objects. For more information and workarounds, see “Known Issues” in the Single Pass Stereo Rendering section of Advanced Rendering Features.

Unity 5 5.6.3p2-5.6.4p1

  • The Unity engine uses projection matrix calculations that are at variance with the Oculus SDK, causing VR scenes to have the wrong parallax, which may cause discomfort.


General Unity Known Issues

This section details known issues with Unity that are not tied to a specific version. Issues are grouped by most closely related subject.

Subject

Known Issues

Unity

  • Unity has a known issue such that parenting one VR camera to another will compound tracking twice. As a workaround, make them siblings in the GameObject hierarchy.

Windows 10

  • If you experience long UI stalls or poor performance with the Unity Editor when targeting Rift on Windows 10, please run Windows Update to ensure that you have the latest version of Windows 10.
  • All Unity versions with Oculus runtime 1.17+ and Windows 10 + Creators Update: This combination results in spurious WM_DEVICECHANGE reports in the Editor, even in non-VR projects. Many users will notice no impact, but users connected to certain USB devices may find the Editor becomes non-responsive and needs to be terminated from Task Manager. To mitigate, please update to the Beta runtime available on our Public Test channel. We are currently working with Unity and Microsoft on a permanent solution.

Rift

  • Guardian System API: ovr_SetBoundaryLookAndFeel currently does not take effect if the HMD is not worn when the call is made (e.g., on Start).
  • Transparent VR Compositor Layers do not currently support multiple layers of occlusion.
  • For Mixed Reality Capture, ZED Camera users should upgrade their SDK version to 2.3.1 or later. Previous versions are not compatible.

Mobile

  • A known bug in Unity causes a deterioration of performance in mobile applications when the back button is used to enter the Universal Menu and then to return to the application. It particularly affects applications that use multi-threading or which have high CPU utilization, and S7 (Europe) and S8 (global) phones. This bug is fixed in Unity versions 2017.3.0b9 , 2017.2.0p3, 2017.1.2p4, and 5.6.4p2.
  • Do not use Utilities 1.11.0 due to a crash when returning to focus from Universal Menu or Quit to Home dialog.
  • When Single Pass Stereo rendering is enabled, building projects will fail with the error message “Shader error in 'Mobile/Bumped Detail Diffuse'” in certain cases. For more information, see “Known Issues” in the Single Pass Stereo Rendering section of Advanced Rendering Features.
  • (Gear VR) Flickering or left/right eye mismatching can occur when you have an input attribute value pass through to a pixel shader directly on Mali GPUs such as those in Samsung phones (used in Gear VR HMDs). This is because the ARM driver specifically targets such "volatile" data and tries to optimize for it, inadvertently creating the issue. A workaround is to try to use a modified version of the original value in some way. For example, instead of passing input value a directly through to shader value b, set b = a + 0.0001; which will prevent the driver from treating b differently.


Package Description

Unity versions 5.1 and later provide built-in VR support for the Oculus Rift, Samsung Gear VR, and Oculus Go. The Unity package includes prefabs, C# scripts, sample scenes, and more to assist with development. For more information, see our Unity Getting Started Guide.

For information on which versions of the Unity Editor are supported, please see Compatibility and Version Requirements.

Be sure to review our Downloads page for other useful tools to assist development, such as the Unity Sample Framework. For more information on Oculus resources for Unity developers, please see Other Oculus Resources for Unity Developers.