Upgrading to 2.0.0

Turian 2.0.0 batches every breaking change of its first month into one release, so a 1.x project upgrades once. Each section below says what changed, who is affected and what to do. Most projects only need the first three: bricks, services and Transform. Scene, prefab and data asset files keep their ids and need no conversion.

Change Who is affected Effort
Camera rigs and UI are bricks projects using camera rigs or in-game UI a manifest and two using lines
Services are injected scripts using Input, Localization or RuntimeServices replace static calls
Transform is a value scripts that write node.Transform.Position and similar mostly search and replace
Shared attributes scripts naming attributes by full name, [HideInEditor], [ShowInEditor] rename and rebuild
IdClass is IdObject plugins using the identity API rename and rebuild
Stricter data asset variants hand-edited variant files fix what the error reports
Gaya hosts and plugins custom Gaya hosts, chrome or appearance code implement two members

Camera rigs and UI are bricks

What changed: the Follow, Orbit, Free Fly and FPS camera rigs moved out of the engine core into the built-in brick org.mass4.turian.cameras (namespace Turian.Cameras). The in-game UI, with .ui documents, .uss style sheets and their components, moved into org.mass4.turian.ui. New projects install both; existing projects must declare them.

Who is affected: 1.x projects that use a camera rig component or in-game UI.

What to do:

  1. Create Bricks/manifest.json in the project folder and list the built-in bricks you use:

    {
      "dependencies": {
        "org.mass4.turian.cameras": "builtin:org.mass4.turian.cameras",
        "org.mass4.turian.ui": "builtin:org.mass4.turian.ui"
      }
    }
    
  2. Add using Turian.Cameras; to scripts that name the camera components.

  3. Add using Turian.Engine.UI; to scripts that use UI types. New projects no longer get this namespace as a global using.

  4. Commit Bricks/manifest.json and the Bricks/packages-lock.json Turian writes next to it.

Scenes and prefabs need no changes: the components keep their type ids. Until the brick is installed they load as missing components, and their assets are skipped without touching the .meta files, so installing the brick brings everything back. See Bricks for everything else bricks can do.

Services are injected

What changed: the process-wide service locator and the static classes built on it are gone. Each runtime session (the exported game, a Play Mode run, a headless test) has its own dependency injection container, and scene objects receive services through properties marked [InjectService].

Who is affected: scripts that call the static Input or Localization classes, or RuntimeServices.

What to do:

1.x 2.0
Input.IsKeyDown(Key.W) an injected IInputSource, then Input.IsKeyDown(Key.W)
Localization.T("key"), Localization.SetLocale(...) an injected LocaleService
RuntimeServices.GetRequired<T>(), TryGet<T>() an [InjectService] property, or Component.Services.GetService(typeof(T))
RuntimeServices.Configure(...) a class implementing IEngineServiceModule
public class Patrol : Component
{
    [InjectService, JsonIgnore]
    public IInputSource? Input { get; private set; }

    public override void OnUpdate(float deltaTime)
    {
        if (Input?.IsKeyDown(Key.W) == true)
            Node.Position += Vector3.UnitZ * deltaTime;
    }
}

Mark injected properties [JsonIgnore] so scenes do not save them. Use [InjectService(Optional = true)] when the component must also work where the service is absent, such as a scene previewed in Studio with no input routed. Register your own services by implementing IEngineServiceModule.ConfigureServices(IServiceCollection); Turian finds the modules in your game's assemblies.

Transform is a value

What changed: Transform is now an immutable readonly record struct instead of a class with change events. A node caches its global transform until it or an ancestor changes.

Who is affected: scripts that assign to a transform's members, subscribe to transform events, or pass null as a parent transform.

What to do:

1.x 2.0
node.Transform.Position = p; node.Position = p;
node.Transform.Orientation = q; node.Orientation = q; (also Rotation and Scale)
several members at once node.Transform = node.Transform with { Position = p, Scale = s };
node.OnGlobalTransformInvalidated += ... removed: compare node.GlobalTransform with the value you kept
transform.PropertyChanged += ... removed: transforms no longer change in place
local.AddParent(null) local.AddParent(Transform.Identity)

New overloads such as GetComponentsInChildren<T>(List<T>) fill a list you pass in, so queries that run every frame no longer allocate.

Shared attributes

What changed: the generic Inspector attributes and the form generator behind the Inspector moved into Guinevere's MASS4.Attributes and Autoformers packages, so any Gaya application can use them. Attributes that only make sense for games stay in Turian.

Who is affected: scripts that name attributes by their full name, use [HideInEditor] or [ShowInEditor], and precompiled plugins.

What to do:

  1. Add using MASS4.Attributes; where you use the shared attributes. Projects created by 2.0 import it automatically.
  2. Update fully qualified names, for example Turian.TypeIdAttribute to MASS4.Attributes.TypeIdAttribute.
  3. Rename [HideInEditor] to [Hide] and [ShowInEditor] to [Show].
  4. Rebuild scripts and precompiled plugins against the 2.0 assemblies.

Serialized data, package.json and Bricks/manifest.json formats and type GUIDs are unchanged.

IdClass is IdObject

What changed: the engine base type that gives objects an instance id is renamed. Ids stay Guid values.

Who is affected: scripts and plugins that use the identity API directly.

What to do: replace Turian.Engine.Core.IdClass with Turian.Engine.Core.IdObject, AssetManager.OpenIdClass with OpenIdObject, and IdClassOpened with IdObjectOpened, then rebuild. Type GUIDs and serialized instance ids are preserved, so scene, prefab and data asset files need no migration.

Stricter data asset variants

What changed: a data asset variant now refuses anything that would quietly change what it is. An override cannot replace the asset's id or type, a variant must keep its base's type, and unknown keys in the __Variant block fail instead of being ignored.

Who is affected: only variant files edited by hand. Variants created in Studio or with turian-cli variant already follow these rules.

What to do: open the project, read the error each refused variant reports, and remove the offending key or point the variant at a base of the right type.

Gaya hosts and plugins

What changed: Studio's menu, project switcher and play controls now live in an application bar that can replace the operating system's title bar, and window appearance settings moved into Gaya.

Who is affected: custom Gaya hosts, plugins that contribute chrome, code that reads appearance settings, and code that uses Guinevere's AppBar directly.

What to do:

  1. If you implement IChromeRegistry, add Replace(ChromeDescriptor) and Remove(string). Plugins can keep calling Register; use Replace for an id that exists and Remove when unloading.
  2. Replace Gaya.Plugin.Turian.AppearanceSettings and WorkbenchWindowSettings with Gaya.Host.AppearanceSettings, reached through Workbench.Appearance. Stored gaya.turian.appearance and gaya.window values migrate automatically.
  3. Replace gui.AppBar(bar => ...) with using (gui.AppBar()) and put widgets directly in the scope. The operating system's window title stays the GuiWindow constructor argument.
  4. Rebuild against the updated SDK, and restart Studio once so it picks the desktop backend.

Coming from Unity

Unity Turian 2.0.0
Input.GetKey(KeyCode.W) injected IInputSource, IsKeyDown(Key.W)
Zenject or VContainer built in: [InjectService] and IEngineServiceModule
transform.position = p; Node.Position = p;
public Transform target; public Node? Target;
public WeaponData weapon; (ScriptableObject) public WeaponData? Weapon; (DataAsset)
Instantiate(scriptableObject) DataAsset.Instantiate(dataAsset)
[HideInInspector] [Hide]
Packages/manifest.json Bricks/manifest.json
scoped registries brick registries, signed with ed25519 keys
prefab variants prefab variants, and data asset variants too

← All docs Edit this page