Importing SDK 1.3.X 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 openTiltFive-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
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 whenTiltFiveManager
is removed in a future SDK version.
After importing SDK 1.3.X (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 aTiltFiveManager
component. Observe that as of SDK 1.3.0, theTiltFiveManager
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 oldTiltFiveManager
, and then disable the oldTiltFiveManager
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 newerTilt Five Prefab
. It’s likely that the old prefab will be removed when we removeTiltFiveManager
(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.
- 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 theTiltFiveManager2
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 calledlegacyInvertGameboardScale
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 aPlayerInput
component to that provided prefab, and make sure there’s aPlayerInputManager
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.X .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 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.