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.

• TiltFiveManager2 exposes the settings required for developers to add multiglasses support to their projects.
• TiltFiveManager2 should be used for all new projects in 1.3.0 forward.
• TiltFiveManager will continue to be supported for a limited time. It will be supported as usual in 1.3.0, then deprecated in 1.4.0, and then removed in 1.5.0.
• We have added a new prefab that implements TiltFiveManager2. The old prefab is still there for compatibility, but it will be removed when TiltFiveManager is removed in SDK 1.5.0.

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:

• The developer is upgrading their project from SDK 1.2.x or earlier.
• Their T5-enabled scenes use an instance of the `Tilt Five Prototype` prefab.
• The developer intends to update all instances of TiltFiveManager in-place using the "Upgrade to TiltFiveManager2" button.

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:

7. 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.
8. 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.
9. 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.
10. 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:

• The developer is upgrading their project from SDK 1.2.x or earlier.
• Their T5-enabled scenes use an instance of the `Tilt Five Prototype` prefab.
• The developer intends to replace all instances of the `Tilt Five Prototype` prefab with the newer `Tilt Five Prefab`. It's likely that the old prefab will be removed when we remove TiltFiveManager (this is planned for SDK 1.5.0), so we recommend replacing the old prefab sometime before then.

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.

7. 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.
8. Find the "Tilt Five Prototype" prefab instance in the inspector.
9. 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.
10. 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.
11. Copy (or move) any non-prefab GameObjects parented underneath any of the old prefab's GameObjects to the new prefab's equivalent GameObjects.
12. Copy any non-T5 components attached to any of the old prefab's GameObjects to the new prefab's equivalent GameObjects.
13. Disable the old prefab.
14. 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:

• Developers can right-click on the old TiltFiveManager and select "Find References in Scene" to get a list of every component in the scene that needs to be updated.
• Single-player games can also take advantage of multiglasses support! Allowing additional players to connect their own glasses while ignoring their wand inputs effectively makes them spectators, which can be a much more satisfying experience than watching the 2D onscreen preview. If your project's performance budget permits it, we encourage developers to support one or more spectators in addition to the primary player.
• The role of the Preview Camera has been split between GlassesSettings' Camera Template and SpectatorSettings' SpectatorCamera. At runtime, the Camera Template is cloned to create eye cameras (making it a good place to attach post-processing or other components), while the Spectator Camera has its pose driven by the specified player's pose. The Spectator Camera also renders the scene if no Mirror Mode is selected. In this release, Spectator Camera is a required field, although this may change in the future. Providing a Camera Template is optional, and simple eye cameras will be generated if nothing is provided. The Camera Template can be a prefab, or it can be shared with Spectator Camera (this is how the original TiltFiveManager is now configured internally).
• Each player can have their own Gameboard gameobject, allowing players' perspectives to move, rotate, or scale independently. If players share a gameboard, they share the same perspective, which can be useful for more traditional board game experiences.
• Culling masks are also available under each player's GlassesSettings, making it easier to hide certain objects from specific players. We hope this provides exciting asymmetric gameplay opportunities for developers.
• The Spectated Player dropdown can be used to preview a specific player’s perspective on screen.
• Loss of tracking fallback modes for the glasses and wands are now exposed under the "Global Settings" section of TiltFiveManager2, under "Tracking".
• If you were previously using the Input System with action maps, take a look at the "Object Template" field under the Glasses settings in TiltFiveManager2. If a prefab is provided here, it will be instantiated as a child gameobject that follows the pose of each player. To make Action Maps work for players 2-4, simply add a PlayerInput component to that provided prefab, and make sure there's a PlayerInputManager somewhere in the scene hierarchy.
• When setting up action maps, to assign an action to a specific wand, you can now use the LeftHand and RightHand controls in the Action Maps UI (e.g. "XR Controller > Tilt Five Wand > Tilt Five Wand (RightHand) > One" or "<WandDevice>{LeftHand}/Two").

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.