Importing SDK 1.4.0 into Unity

Close Unity
Navigate to the Unity project in the file explorer
Delete Assets/Tilt Five/ and Assets/Tilt Five.meta
Open the Unity project
Go to Assets -> Import Package -> Custom Package...
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

📝 Note: After importing the package in some versions of Unity, you may get an error in the console that says MonoScript is registered as both Editor and Runtime script! and then be unable to edit the Tilt Five Manager 2 settings (instead of the settings, it will contain a the text "Multi-object editing not supported"). Restarting the Unity editor should resolve the issue.

Upgrading the Project from SDK 1.3.x or Earlier Versions to 1.4.x

There are numerous changes in 1.4.0 where the API is different from prior releases, however most 1.3.x projects should not have significant issues adopting 1.4.0

The minimum supported Unity Engine version for 1.4.0 is 2019.4 LTS. The prior support level was 2018.4 LTS.
The default for the Gameboard scaling in earlier versions was the inverse of the current default. If your project used Gameboard scaling you may have to explicitly set the legacy scaling option to true to display content at the scale intended.
Some functions that were in Glasses.cs are now in a new SystemControl.cs: SetApplicationInfo() and SetPlatformContext() can now be found in SystemControl.cs.
Many functions in Glasses.cs which were not aware of multiple Glasses being connected were deprecated, and some versions which included player identifiers supercede them.
Native library calls are now internal instead of public visibility; in the unlikely case your code was calling these functions directly, compilations will fail now.
The Wand primary and secondary Wand enum values were deprecated in 1.3.0 and will now cause compile errors. They must be changed to right or left.
A 60fps target frame rate will be enabled by default; many projects were already doing this work but it is a recommended setting for the best user experience. It can be disabled in the Unity Editor for the TiltFiveManager2 component.

Upgrading the Project from 1.2.x or Earlier Versions to 1.4.x

The change most likely to affect developers’ projects is that SDK 1.3.0 introduced 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 and forward.
TiltFiveManager will continue to be supported for a limited time. It will be supported as usual in 1.3.X, then deprecated in 1.4.X, and then removed in a future version.
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 a future SDK version.

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

OPTION 1: 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 past 1.4.X).

The basic steps would look like this:

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.
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.
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.
Repeat steps 7-9 for every scene in the project that implements Tilt Five support.

OPTION 2: 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 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.

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.
Find the Tilt Five Prototype prefab instance in the inspector.
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.
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.
Copy (or move) any non-prefab GameObjects parented underneath any of the old prefab's GameObjects to the new prefab's equivalent GameObjects.
Copy any non-T5 components attached to any of the old prefab's GameObjects to the new prefab's equivalent GameObjects.
Disable the old prefab.
Repeat steps 7-13 for every scene in the project that implements Tilt Five support.

Next Steps 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".
In SDK 1.3.1 and later, change your GameBoard scale settings. In SDKs prior to version 1.3.1 the GameBoard scale was specified in an inversion of common expectation, where larger magnitude scales cause content to appear smaller. Starting in 1.3.1 SDK the ScaleSettings object has a boolean property called legacyInvertGameboardScale to invert the scaling which defaults to true for compatibility. New content should set this to false and adjust scaling as needed, and when upgrading consider making these changes for your content. In SDK 1.4.X this legacy option will default to false and be considered obsolescent, and in some SDK version after 1.4.X it will disappear completely.
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.

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