Importing SDK 1.3.0 into Unity

  1. Close Unity
  2. Navigate to the Unity project in the file explorer
  3. Delete Assets/Tilt Five/ and Assets/Tilt Five.meta
  4. Open the Unity project
  5. Go to Assets -> Import Package -> Custom Package...
  6. In the Import Package... file picker, navigate to %PROGRAMFILES%\TiltFive\SDK\UnityPlugin\, then select and open TiltFive-Plugin.unitypackage

Upgrading the Project

The change most likely to affect developers’ projects is that SDK 1.3.0 introduces the new TiltFiveManager2 component, which replaces the previous TiltFiveManager.

After importing SDK 1.3.0 (step 6 above), the upgrade process can differ depending on the project implementation.

Update the Existing Prefab

In the simplest case:

Advantage: faster to update the project

Disadvantage: postpones migrating to the new Tilt Five prefab, which will need to happen when the original TiltFiveManager is removed (planned for SDK 1.5.0).

The basic steps would look like this:

  1. Open a scene that implements Tilt Five support via TiltFiveManager. If the project previously used SDK 1.2.x or earlier, this would be any T5-enabled scene.
  2. In the inspector, find and select the GameObject named "Tilt Five Manager" - this should be a child of "Tilt Five Prototype". This GameObject will have a TiltFiveManager component. Observe that as of SDK 1.3.0, the TiltFiveManager now has an "Upgrade to TiltFiveManager2" button.
  3. Press the "Upgrade to TiltFiveManager2" button. This will create a TiltFiveManager2 component, copy the existing settings from the old TiltFiveManager, and then disable the old TiltFiveManager component.
  4. Repeat steps  7-9 for every scene in the project that implements Tilt Five support.

Migrate to the New Prefab

In a slightly more complicated (yet common) case:

Advantage: moving to the new prefab earlier means less work when the old prefab is obsoleted

Disadvantage: more upfront effort, easier to make mistakes when going through a large number of scenes

The steps change in this scenario - a button to automatically swap in the new prefab would be difficult to implement since developers may have decorated their prefab instances with additional Components or child GameObjects.

  1. Open a scene that implements Tilt Five support via TiltFiveManager. If the project previously used SDK 1.2.x or earlier, this would be any T5-enabled scene.
  2. Find the "Tilt Five Prototype" prefab instance in the inspector.
  3. Add an instance of the "Tilt Five Prefab" prefab to the scene. It should be a sibling of the old prefab instance in the scene in terms of parent-child hierarchy.
  4. Copy the various settings from the TiltFiveManager in the old prefab to the TiltFiveManager2 in the new prefab. Most of these settings will be associated with Player 1, though the glasses settings for Mirror Mode and Tracking Failure Mode have become global settings.
  5. Copy (or move) any non-prefab GameObjects parented underneath any of the old prefab's GameObjects to the new prefab's equivalent GameObjects.
  6. Copy any non-T5 components attached to any of the old prefab's GameObjects to the new prefab's equivalent GameObjects.
  7. Disable the old prefab.
  8. Repeat steps 7-13 for every scene in the project that implements Tilt Five support.

Notes for Both Upgrade Methods Above

In either scenario, at this point, it's time to replace all references to TiltFiveManager in the developers' scripts and replace them with references to TiltFiveManager2.

Once the references are updated, any internal logic in those scripts relying on TiltFiveManager's API will also need to be updated to use TiltFiveManger2's API (e.g. querying the current content scale would change from `myTiltFiveManager.scaleSettings.contentScaleRatio` to `myTiltFiveManager2.playerOneSettings.scaleSettings.contentScaleRatio`). Most of the API changes will be as simple as adding `playerOneSettings` in the middle of their existing calls. One notable exception would be Mirror Mode, which has moved from GlassesSettings to SpectatorSettings.

Any references in the scene to the old prefab’s other components/GameObjects, such as “Tilt Five Camera”, “Tilt Five Game Board”, etc should also be updated to point at the equivalent GameObjects in the new prefab.

Once all settings are copied, children moved, references fixed, and scripts updated, it should be safe to remove the old TiltFiveManager or Tilt Five Prototype prefab from all of the T5-enabled scenes, at which point the upgrade's finished.

Upgrade Tips:

Other Suggestions

For some projects, it may make sense to add the Tilt Five Prefab to a custom prefab. Instances of that prefab could be added to the various scenes in a given project, rather than directly adding an instance of the Tilt Five Prefab. If there is ever a “TiltFiveManager3” at some point in the future (we hope to avoid this 😅), this configuration would let developers make a single update to their custom prefab, and the change would be reflected in all of their scenes.

We also recommend that single-player applications use TiltFiveManager2 as well - simply clicking the subtract (-) button in TIltFiveManager2 until only one player remains will effectively result in behavior equivalent to TiltFiveManager.

Additional Background

Implementing support for multiple glasses required us to reconsider some of our initial assumptions regarding the TiltFiveManager component in Unity. It became clear that some settings should be made independent from any particular pair of glasses, while others should be strongly associated with specific glasses to provide developers with the most flexibility.

However, making these changes to TiltFiveManager seemed likely to cause issues with developers' settings being lost while importing the 1.3.0 .unitypackage file. To avoid imposing on developers by making a breaking change and risking data loss, we opted to implement TiltFiveManager2 instead of heavily modifying TiltFiveManager.

Contact Us

SDK 1.3.0 provides new opportunities for immersive local multiplayer experiences. While we've tried to strike a balance between compatibility and ease of upgrade, we're not entirely satisfied with this upgrade process. We welcome all feedback on ways we can improve the upgrade process and the SDK itself.

Please reach out to us at devrel@tiltfive.com if you have any comments, suggestions, or questions.