Introduction to Tilt Five and Unity

A Tilt Five system is composed of glasses, a special game board with a retroreflective surface, and a motion-tracked wand controller. The glasses project an image from each eye to the game board, which reflects back to the player’s eyes to achieve a stereoscopic effect. The glasses track their position relative to the game board, as well as the position of the wand.

To use this system with a Unity project, we provide a plugin to act as a bridge between the Tilt Five hardware and Unity.

Requirements

  • OS: Windows 10 or 11 / Linux Ubuntu 20.04 amd64 (Requires Tilt Five SDK 1.3.1 or later)
  • Unity 2018 LTS or newer for Windows and Linux targets
  • Unity 2019 LTS or newer for Android targets

Add the Tilt Five Unity Plugin to your Project

Add the custom package (first time)

If you’re upgrading from a previous Tilt Five Unity plugin package, please go to the Upgrading section below this one instead.

  1. If you haven’t already, now is the time to download our latest software, including the Unity plugin. Install the latest driver release and the latest SDK release.
  2. Within the SDK folder, navigate to the Setup subdirectory and follow the instructions within to set up your new Tilt Five hardware.
  3. In Unity, create or open a project.
  4. From the SDK folder (on Windows this is %PROGRAMFILES%\TiltFive\SDK\UnityPlugin\), import TiltFive-Plugin.unitypackage. You can do this in two ways, either (a) drag and drop the file into your Unity Project panel, or (b) from the Unity Assets menu, choose Import Package > Custom Package, then browse to and select the TiltFive-Unity-SDK.unitypackage file and click Open.
  5. In the Import Unity Package pane, click All to select all the items (they should be selected by default)

Upgrade from a previously installed plugin

If you have never added the Tilt Five Unity plugin to your project, refer to the previous section instead.

  1. Close Unity
  2. Navigate to the Unity project in the file explorer
  3. Delete the Assets/Tilt Five/ directory completely
  4. Open the Unity project

    Recent versions of Unity may present a dialog and ask if you want to enter “Safe Mode” because some of the files referenced in the Tilt Five directory are missing at this point. You can safely chose the “Ignore” option here.

  5. Go to Assets -> Import Package -> Custom Package…
  6. In the Import Package… file picker, navigate to the installed SDK path (on Windows this is %PROGRAMFILES%\TiltFive\SDK\UnityPlugin\), then select and open TiltFive-Plugin.unitypackage
  7. Close and re-open the Unity editor

If upgrading from 1.2.2 or earlier to 1.3.X: please refer to Upgrading Unity Projects to SDK 1.3.X for additional steps and tips for upgrading your project.

Create a Tilt Five Capable Scene

Now that you have imported the plugin, it’s time to display something on the glasses. There are three required components that must be present in a Tilt Five capable scene: a Game Board, a Camera to be controlled by the headset’s positional data, and a Tilt Five Manager. These instructions will give you the simplest Tilt Five capable scene with the tracking origin at [0.0, 0.0, 0.0].

  1. Create a new scene.
  2. Disable or delete the Main Camera GameObject.
  3. Add a cube to the scene at [0.0, 0.5, 0.0].
  4. In the Project window, under Assets > Tilt Five > Prefabs, drag the Tilt Five Prototype prefab into the Hierarchy, and ensure that its Transform component has a position of [0.0, 0.0, 0.0] and a rotation of [0.0, 0.0, 0.0].
  5. Press Play to run the scene in the editor.

Configure Settings

  • Enabling multisample antialiasing (MSAA) is recommended to smooth out sharp edges.

Platform Specifics

As of SDK 1.3.1, three platforms are available for content, and each has some specific capabilities and limitations.

Windows

Graphics API

  • DirectX 11 is required on Windows - OpenGL rendering is not officially supported

Android

Android Unity support first appeared in SDK 1.3.1 and is limited to Unity versions 2019 LTS and later.

Main Manifest Override

The Tilt Five Android Unity plugin requires a custom Android Activity, which is specified in the Main Manifest. How you integrate this depends on if you’re already overriding the Main Manifest. To check if you’re already overriding your Main Manifest, look in your Project window under Assets/Plugins/Android/AndroidManifest.xml. If the file is present, you are already overriding.

If you are not overriding your Android Main Manifest:

  • In your Project window, create a folder under Assets called Plugins
  • In your Project window, create a folder under Assets\Plugins called Android
  • Copy Assets/Tilt Five/AndroidManifest/AndroidManifest.xml to Assets/Plugins/Android/AndroidManifest.xml

If you are overriding your Android Main Manifest:

  • Open Assets/Tilt Five/AndroidManifest/AndroidManifest.xml, search for TiltFiveCustomAndroidManifest and follow the instructions
  • Open Assets/Tilt Five/Runtime/Player/Glasses/Display.cs, search for TiltFiveCustomAndroidManifest and follow the instructions

Workaround required for Unity 2019.4

Unity 2019.4 ships with an older gradle version and requires a workaround to support the package visibility <queries> element in the manifest.

Download Gradle 5.6.4 or later, extract it, and make note of where you placed the tool.

In the Unity Editor window, open the Preferences window and navigate to the External Tools page. Uncheck the box that says “Gradle Installed with Unity (recommended)” and set the Gradle path to where you extracted the Gradle tool above.

Go to Project Settings > Player > Android > Publishing Settings > Build. Ensure the following two boxes are checked:

  • Custom Main Gradle Template
  • Custom Launcher Gradle Template

After those two options are checked, Unity will generate the two template files in Assets/Plugins/Android.

In both of those files, make the following two edits:

  1. Remove the comment at the top of the file that says

     // GENERATED BY UNITY. REMOVE THIS COMMENT TO PREVENT OVERWRITING WHEN EXPORTING AGAIN

  2. Insert the following code at the top of the file:

     buildscript {
     repositories {
         google()
         mavenCentral()
     }
     dependencies {
         // Must be Android Gradle Plugin 3.6.0 or later. For a list of
         // compatible Gradle versions refer to:
         // https://developer.android.com/studio/releases/gradle-plugin
         classpath 'com.android.tools.build:gradle:3.6.0'
     }
 }

 allprojects {
   repositories {
       google()
       mavenCentral()
       flatDir {
         dirs 'libs'
       }
   }
 }

Graphics API

We currently do not support Vulkan, which may be the default for your Android Project. To ensure that OpenGLES3 is the only option, follow the below instructions:

  • Project Settings > Player > Android > Other Settings > Rendering:
    • Ensure that ‘Auto Graphics API’ is unchecked
  • Project Settings > Player > Android > Other Settings > Rendering > Graphics APIs:
    • Ensure that only OpenGLES3 is present in the list (remove any others)

Target Architecture

ARMv7 and ARM64 are the only currently supported Android architectures. To ensure that it’s correctly configured, follow the below instructions:

  • Project Settings > Player > Android > Other Settings > Configuration > Target Architectures:
    • Ensure that only ARM64 and/or ARMv7 are checked (uncheck any others)

Note that as of the 2020 LTS version, Unity’s Mono scripting backend does not support ARM64. If you plan to use ARM64 only, you may need to switch to IL2CPP. To do so, follow the below instructions:

  • Project Settings > Player > Android > Other Settings > Configuration > Scripting Backend:
    • Ensure that IL2CPP is selected

Linux

Linux Unity support is experimental and as of its initial release in SDK 1.3.1 it is not fully tested.

Note: Linux binaries as of Tilt Five Drivers 1.3.1 currently require host computer CPUs with AVX2 support (Issue #945) so may not run on all Ubuntu 20.02 supported hosts.

Graphics API

  • As of 1.3.1, OpenGL rendering is the only supported option on Linux
Tags: getting_started