This codelab is an introduction to how to take a first person game made in Unity and enhance it to have a Virtual Reality mode using the Google Cardboard plugin powered by Unity.

What you'll learn

What you'll need

Game Summary

For this codelab, we'll be using a simple and entertaining game, called "Lollygagger". The main game play is to travel along a path, atop a robot, shooting Lollipop "cannonballs" at the Androids that are lollygagging around. Key features of note are:

How will you use this tutorial?

Read through it only Read it and complete the exercises

How would you rate your experience with building Unity apps?

Novice Intermediate Proficient

How would you rate your experience with building Android apps?

Novice Intermediate Proficient

First you need the Cardboard SDK for unity

You can either download all the sample code to your computer...

Download Zip

...or clone the GitHub repository from the command line.

$ git clone https://github.com/googlesamples/cardboard-unity.git

Next you need the unity asset package containing the sample game. You can download this here:

Download lollygagger_step0.unitypackage

First, let's build and run the non-Cardboard version of the game. From there, we'll add Cardboard support.

Configure Unity

  1. Start Unity. If you have not developed an Android application with Unity before, make sure you configure the Android SDK within Unity. In Unity, click Preferences > External Tools > Android SDK Location, then select the folder where you downloaded and unzipped the Android SDK.
  2. Click File > New Project and create a new project named ‘Lollygagger_cardboard'.

Import the game assets

Import the sample game scenes and assets into your project:

Configure the Android player

  1. Configure Unity to build an Android application
  2. From the menu: click File > Build Settings...
  3. Select Android in the platform list
  4. Click Switch Platform
  5. Add the game scenes to the build.
  6. In the project explorer, select Assets
  7. Drag and Drop Assets/MainMenu scene to the "Scenes In Build" list within the Build Settings dialog.
  8. Then drag and drop Assets/GameScene scene into the list under MainMenu.

  1. Configure the Unity player settings
  2. Click Player Settings... in the Build Settings dialog
  3. Then expand "Resolution and Presentation" section by clicking on it.
  4. Set the application default orientation to Landscape Left. This is the correct orientation for the application when the phone is in Cardboard.

  1. Expand the "Other Settings" section by clicking on it.
  2. Enter a unique Bundle ID, this follows .Net namespace (or Java package) naming rules. Typically this is of the form: com.<yourcompany>.<appname>

  1. Save your project! Better safe than sorry :)
  2. Connect a device build and run! When prompted for a name for the APK file, enter Lollygagger.apk.

Congratulations! If you can play the starter project game on your Android device, you are now ready to add Cardboard!

Troubleshooting

Even the most simple things can have gotchas! Here are a couple and what to do about it. If you're still having problems ask for help!

Issue

Solution

Issue: Error building Player: UnityException: Bundle Identifier has not been set up correctly

Solution: Set the bundle identifier to something other than the default. This is in the player settings > Other Settings section.

In this lesson, you'll import the Cardboard SDK into the Unity project. This gives you all the scripts and easy to use prefabs for quickly and easily enabling the game to be played in virtual reality mode.

Add the Cardboard SDK to the project

  1. Unzip the Cardboard SDK if you haven't yet
  2. From the menu in Unity: click Assets > Import Package > Custom package
  3. Select CardboardSDKForUnity.unitypackage
  4. Once the package is opened, Unity presents a list of the files within in the package.
  5. Click "Import"

Add cardboard mode to the main menu scene

This step adds the stereo cameras and related scripts which are used by the Cardboard SDK to render the stereoscopic view needed to use Cardboard.

  1. Open the main menu scene. In the project explorer, select the Assets folder, and then double click the MainMenu scene.
  2. Select the Main Camera in the Scene hierarchy.
  3. From the menu, click Component > Cardboard > Update Stereo Cameras. This does the following:
  1. Adds the StereoController script component (controls the rendering of the stereo effect)
  2. Adds the CardboardHead script component (the "head" containing the "eyes")
  3. Creates Left and Right child cameras (aka the "eyes")
  4. Also adds the SkyboxMesh script component (important since we use a skybox background).

Change the UI to be in world space

This step converts the main menu from being mapped to the Screen Space (which is based on the screen dimensions) to be mapped in the World Space (which is based on the 3d coordinates within the scene). This is done so that the menu rendering can be done by the stereo cameras used by Cardboard.

  1. Select Canvas from the Hierarchy window, then in the inspector panel:

Change position to (0, 0, 750)

Change Width and Height to 640 and 480

pivot = (.5, .5)

Change scale to (1, 1, 1)

  1. Associate the Main Camera with the Canvas. This is done so that UI events can be translated from the screen coordinates to the world coordinates.

  1. Check the menu location and size. You can do this by clicking on the Game tab in the scene editor. You should see:

Add the Cardboard mode button to the menu

In this step, we add a button to the menu that will turn on and off "Cardboard Mode". In cardboard mode the stereoscopic rendering is done, in non-cardboard mode it is the normal 2D rendering. Just to make everything easy, we have made a prefab button.

  1. Find the cardboardButton prefab in the project explorer. This is under Assets/Prefabs.
  2. In the Hierarchy panel, expand the Canvas object and the Panel object.
  3. Drag and drop the cardboardButton prefab onto the Panel object in the hierarchy. When you are done, the hierarchy should look like:

Next, we'll write the script that will run when the button is clicked.

Now that there is a button on the menu for switching the cardboard mode, we need to make it do something when it is clicked. So finally we get to write some code!

  1. Create a new script component on the Canvas.

There are two tasks that this script must do. First, it should handle the toggling of Cardboard mode, and second, it must handle the pointer functionality. This is the equivalent of using the mouse on a computer, or your finger on a mobile device. When in Cardboard mode the direction you are looking needs to be treated in the same manner.

Handle Cardboard mode

There are two methods we need to handle the cardboard mode.

  1. When we start figure out which mode we should be in.
  2. When the button to change the mode is clicked, we change the mode and remember which mode we are in.

Open CardboardModeMgr script by double-clicking on it, delete the entire contents and paste in the following code.

using UnityEngine;
using System.Collections;
using UnityEngine.EventSystems;
using System.Collections.Generic;
using UnityEngine.UI;

public class CardboardModeMgr : MonoBehaviour {
    
    // We need a reference to camera which 
    // is how we get to the cardboard components.
    public GameObject mainCamera;


    public void Start()
    {
        // Save a flag in the local player preferences to initialize VR mode
        // This way when the app is restarted, it is in the mode that was last used.
        int doVR = PlayerPrefs.GetInt("VREnabled");
        Cardboard.SDK.VRModeEnabled = doVR == 1;
        CardboardHead head = mainCamera.GetComponent<CardboardHead>();
        head.enabled  = Cardboard.SDK.VRModeEnabled;
        Cardboard.SDK.TapIsTrigger = true;
    }

   // The event handler to call to toggle Cardboard mode.
    public void ChangeCardboardMode ()
    {
        CardboardHead head = mainCamera.GetComponent<CardboardHead>();
        if (Cardboard.SDK.VRModeEnabled) {
            // disabling.  rotate back to the original rotation.
            head.transform.localRotation = Quaternion.identity;
        }
        Cardboard.SDK.VRModeEnabled = !Cardboard.SDK.VRModeEnabled;
        head.enabled  = Cardboard.SDK.VRModeEnabled;
        PlayerPrefs.SetInt("VREnabled", Cardboard.SDK.VRModeEnabled?1:0);
        PlayerPrefs.Save();        
    }
}
  1. Save the script and switch back to the Scene Editor.

Handle VR pointing and clicking

In order to control the game play while in cardboard mode, we need to add an input module to the event system that uses the player's gaze to select or point to objects and use the cardboard trigger as an input event.

  1. In the scene hierarchy, select the EventSystem object.
  2. From the menu, select Component > Scripts > Gaze Input Module.
  3. Make sure the Gaze Input Module is the first input module in the list. You can move the module up in the list by clicking on gear next to Gaze Input Module and selecting Move Up.
  4. Check the box Vr Mode Only in the properties of the Gaze Input Module.

Associate the camera with the other game objects

In order to gain access to the user's direction of view, or gaze, the main camera needs to be made available to these components.

  1. Select the Canvas object in the hierarchy.
  2. Notice in the properties inspector for the Cardboard Mode Mgr component, there is a place for Main Camera.
  3. Click on the circle next to the value and select the Scene tab, then Main Camera object.

Associate the click event with the script

  1. In the scene hierarchy, select the buttonCardboard object(under Canvas/Panel) .
  2. In the properties inspector, scroll down to the On Click () section.
  3. Click the + to add another handler.

  1. Save the scene, and Save the project!

The Cardboard SDK has the facility to preview the stereo rendering in the editor. Using Alt+mouse to move the head around. It is not perfect--specifically the input events can be can get a little confusing since the mouse is present, but it is a good quick way of doing a sanity check.

But enough sanity! Let's build the project again and run the app. Click on the Cardboard Button to go into VR mode, and put your phone in the Cardboard device.

Look around, see how the buttons become selected by just looking at them!

Using the trigger will click the selected button--but be careful!! The main game is not in VR mode (yet) so trying to play the the main game in Cardboard can be a dizzying experience.....

This lesson updates the main game scene to be VR enabled. This involves similar steps that you just did in the previous lesson. Specifically adding the stereoscopic rendering, updating menu UIs and adding trigger support.

Add Cardboard view to the Game Scene

This step adds the stereo cameras and related scripts which are used by the Cardboard SDK to render the stereoscopic view needed to use Cardboard.

  1. Open the game scene. In the project explorer, select the Assets folder, and the double click the GameScene scene.
  2. Select the Main Camera in the Scene hierarchy. Since the game play is in first person, the main camera is a child object of the player.
  3. From the menu, click Component > Cardboard > Update Stereo Cameras. This does the following:
  1. Adds StereoController (controls the rendering of the stereo effect)
  2. Adds CardboardHead (the "head" containing the "eyes")
  3. Creates Left and Right child cameras (aka the "eyes")
  4. Also adds SkyboxMesh (important since we use a skybox background).

Add Cardboard Mode Manager script

Adding this script will initialize cardboard based on the mode selected in the main menu.

  1. In the scene hierarchy, select the Canvas object.
  2. From the menu, select Component > Scripts > Cardboard Mode Mgr.
  3. Set the Main Camera property in the script to the Main Camera.

Add the GazeInputModule script to the EventSystem

The GazeInputModule handles input events, so it needs to be on every scene.

  1. In the scene hierarchy, select the EventSystem object.
  2. From the menu, select Component > Scripts > Gaze Input Module.
  3. Make sure the Gaze Input Module is the first input module in the list. You can move the module up in the list by clicking on gear next to Gaze Input Module and selecting Move Up.
  4. Check the box Vr Mode Only in the properties of the Gaze Input Module.

Save and Run!

  1. File > Save scene
  2. File > Save project
  3. File > Build and run

When you start the game, if it is not in cardboard mode, click on cardboard mode and then Start.

Great News: The scene is in 3D and you can look around the virtual world!

Not So Great News: Shooting, and the menu are not working (yet, but that is why you're here!)

Change Aiming to be based on the gaze of the player

In the 2D world, the finger touch is used to rotate the player in order to aim and shoot. In VR mode, the rotation is done by the actual user, and the Cardboard SDK handles that for you!

  1. Open the MouseLooking script. This is found in the project explorer, Assets/Scripts.
  2. Then at the top of the Update() method paste the following. It does not affect the application other than saving a few precious CPU cycles.
if (Cardboard.SDK.VRModeEnabled) {
           return;    
 }
  1. Save the script and return to the Unity editor.

Wonderful - all those CPU cycles are yours to keep!

Add firing using the cardboard button or trigger

  1. Open the Shooting script. This is found in the project explorer, Assets/Scripts.
  2. In the Update() method, find the if statement:
// Replace this...
if(Input.GetButtonUp("Fire1") && ! GameManager.Instance.IsMenuShowing)

And change it to:

// Cardboard-enabled
if((Cardboard.SDK.Triggered || Input.GetButtonUp("Fire1")) && 
     !GameManager.Instance.IsMenuShowing)
  1. Save the script and return to the Unity editor.
  2. Save the scene and the project.
  3. Build and run!

Make the ending menu VR compatible

This is similar to what we did in the MainMenu scene to make the menu appear in Cardboard mode. As you recall, the UI canvas needs to be mapped in the World Space (which is the 3d coordinates within the game) so that the menu rendering can be done by the stereo cameras used by Cardboard.

  1. Select Canvas from the Hierarchy window, then in the inspector panel:
  1. Set the Event Camera to be the Main Camera (By now you should know how to do this!) Hint: click the circle next to the property and select the Main Camera.

  1. Save the project
  2. Build & run and be amazed!

Congratulations!!! You've just taken a giant step to the exciting world of Cardboard using Unity. But as you can imagine, there are so many more facets to creating awesome Cardboard games.

Here are some references for you to explore on your own time.

Cardboard Design Lab

Overview of Cardboard

Android Launch Checklist

Performance Optimizations