Scenes

A scene is a .prefab file holding a node tree (see Scenes and scene nodes). A built game opens the startup scene named in Player Settings; from there, your scripts load the rest through the scene manager.

Getting the scene manager

ISceneManager? scenes;

public override void OnAwake() => scenes = RuntimeServices.TryGet<ISceneManager>();

The same code works in Studio's Play Mode and in an exported game.

Scene references as fields

Expose a scene as an asset reference and pick it in the Inspector:

public class LevelExit : Component
{
    public AssetReference<Prefab>? NextLevel;
}

Load modes

// Replace every loaded scene with the next level.
await scenes.LoadSceneAsync(NextLevel!.AssetId, LoadSceneMode.Single);

// Add a scene on top of the current ones — a HUD, a streamed area, a debug overlay.
var hud = await scenes.LoadSceneAsync(hudScene.AssetId, LoadSceneMode.Additive);

LoadSceneAsync returns a LoadedScene with its AssetId, Name and RootNode. Scene files load on a background task; the returned task completes once the scene is tracked and ready to tick.

The active scene

One loaded scene is active. InstantiateAsync(prefab) without a parent adds the copy to the active scene's root.

scenes.SetActiveScene(hud);            // or SetActiveScene(assetId)
var current = scenes.ActiveScene;
foreach (var scene in scenes.LoadedScenes) Log.Logger.LogInformation("{Scene}", scene.Name);

Unloading

scenes.UnloadScene(hud);               // by LoadedScene
scenes.UnloadScene(hudScene.AssetId);  // by asset id
scenes.UnloadAllScenes();

Unloading runs OnDisable and OnDestroy on the scene's components.

Loading the same scene twice

DuplicateLoadPolicy decides what happens when a scene that is already loaded is requested again:

Objects that survive scene changes

scenes.PersistentRoot is a node that is never unloaded and is updated every frame alongside the loaded scenes — Turian's equivalent of Unity's DontDestroyOnLoad. Put music players, save-game managers and similar objects under it:

var musicPlayer = await scenes.InstantiateAsync(musicPrefab, scenes.PersistentRoot);

Example: a timed level switch

public class SceneSwitcher : Component
{
    public AssetReference<Prefab>? Next;
    public float Seconds = 5f;

    ISceneManager? scenes;
    float elapsed;
    bool loading;

    public override void OnAwake() => scenes = RuntimeServices.TryGet<ISceneManager>();

    public override void OnUpdate(float deltaTime)
    {
        if (loading || Next is null || scenes is null) return;

        elapsed += deltaTime;
        if (elapsed < Seconds) return;

        loading = true;
        _ = scenes.LoadSceneAsync(Next.AssetId, LoadSceneMode.Single);
    }
}

← All docs Edit this page