This guide shows you how to use the Google Cardboard XR Plugin for Unity for Unity to create your own Virtual Reality (VR) experiences.
You can use the Cardboard SDK to turn a smartphone into a VR platform. A smartphone can display 3D scenes with stereoscopic rendering, track and react to head movements, and interact with apps by detecting when the user presses the viewer button.
To get started, you'll use HelloCardboard, a demo game that demonstrates the core features of the Cardboard SDK. In the game, users look around a virtual world to find and collect objects. It shows you how to:
- Set up your development environment
- Download and build the demo app
- Scan the QR code of a Cardboard viewer to save its parameters
- Track the user’s head movements
- Render stereoscopic images by setting the correct distortion for each eye
- Turn VR mode on and off
Set up your development environment
Software requirements:
- Unity 2019.3.15f1 or later
- Make sure to include Android and iOS Build Support during installation.
- Git must be installed and the
git
executable must be on thePATH
environment variable. See Unity's package manager git support docs for more details.
Import the SDK and create a new project
Follow these steps to import the Unity SDK and create a new project.
- Open Unity and create a new 3D project.
- In Unity, go to Window > Package Manager.
- Click + and select Add package from git URL.
- Paste
https://github.com/googlevr/cardboard-xr-plugin.git
into the text entry field.
The package should be added to the installed packages. - Navigate to the Google Cardboard XR Plugin for Unity package. In the Samples
section, choose Import into Project.
The sample assets should be loaded intoAssets/Samples/Google Cardboard/<version>/Hello Cardboard/Assets
. - Navigate to
Assets/Samples/Google Cardboard/<version>/Hello Cardboard/Assets/Scenes
, select Add Open Scenes, and choose HelloCardboard to open the sample scene.
Configuring Android project settings
Navigate to File > Build Settings.
- Select Android and choose Switch Platform.
- Select Add Open Scenes and choose HelloCardboard.
Player Settings
Resolution and Presentation
Navigate to Project Settings > Player > Resolution and Presentation.
- Set the Default Orientation to Landscape Left.
- Disable Optimized Frame Pacing.
Other Settings
Navigate to Project Settings > Player > Other Settings.
- Choose
OpenGLES2
, orOpenGLES3
, or both in Graphics APIs. - Select
IL2CPP
in Scripting Backend. - Select desired architectures by choosing
ARMv7
,ARM64
, or both in Target Architectures. - Select
Require
in Internet Access. - Specify your company domain under Package Name.
Publishing Settings
Navigate to Project Settings > Player > Publishing Settings.
- Select
Custom Main Gradle Template
in the Build section. Add the following lines to the dependencies section of
Assets/Plugins/Android/mainTemplate.gradle
:implementation 'com.android.support:appcompat-v7:28.0.0' implementation 'com.android.support:support-v4:28.0.0' implementation 'com.google.android.gms:play-services-vision:15.0.2' implementation 'com.google.protobuf:protobuf-lite:3.0.0'
If Target API Level is set to API Level 29
or Automatic (highest
installed)
(resulting in API Level 29), the following steps are also required:
- Select 'Custom Main Manifest' in the Build section.
Add the following attribute to the
application
tag ofAssets/Plugins/Android/AndroidManifest.xml
:<application android:requestLegacyExternalStorage="true" ... > ... </application>
XR Plug-in Management Settings
Navigate to Project Settings > XR Plug-in Management.
- Select
Cardboard XR Plugin
under Plug-in Providers.
Build your project
Navigate to File > Build Settings.
- Select Build, or choose a device and select Build and Run.
Configuring iOS project settings
Navigate to File > Build Settings.
- Select iOS and choose Switch Platform.
- Select Add Open Scenes and choose HelloCardboard.
Player Settings
Resolution and Presentation
Navigate to Project Settings > Player > Resolution and Presentation.
- Set the Default Orientation to Landscape Left.
Other Settings
Navigate to Project Settings > Player > Other Settings.
- Disable the Auto Graphics API option.
- Choose
OpenGLES2
, orOpenGLES3
, or both in Graphics APIs. - In Camera Usage Description, write
Cardboard SDK requires camera permission to read the QR code (required to get the encoded device parameters).
. - In Target minimum iOS Version, write
11.0
. - Specify your company domain under Package Name.
XR Plug-in Management Settings
Navigate to Project Settings > XR Plug-in Management.
- Select
Cardboard XR Plugin
under Plug-in Providers.
Build your project
Navigate to File > Build Settings.
- Select Build or Build and Run.
Turning VR mode on and off
The Unity XR Plugin Management API lets you turn VR mode on or off for the Google Cardboard XR Plugin for Unity. End-user documentation and usage examples are available in Unity's End-user documentation.
The VrMode scene in HelloCardboard sample shows a basic usage of the aformentioned
API. In this scene, VR mode can be turned off by tapping exit , and can
be turned on again just by tapping anywhere on the screen. Check VrModeController.cs for details about how this is performed.
Next steps
- Review the Cardboard branding guidelines.