SceneManager

Manages scene lifecycle operations including loading, unloading, active-scene switching, and hierarchy instantiation. Scenes and prefabs share the same serialized node-hierarchy format; the distinction is whether the loaded hierarchy is tracked as a loaded scene or instantiated under another root.

Remarks

This class is intended to be driven from a single thread (typically the game loop). The internal state is guarded by a lock so that out-of-band calls (editor refreshes, asset watcher callbacks) cannot corrupt the loaded-scene list mid-tick, but lifecycle callbacks on nodes and components are invoked without the lock held.

Properties

LoadedScenes

(IEnumerable) : Gets a snapshot of all currently loaded scenes.

ActiveScene

(LoadedScene?) { get; set }: Gets or sets the currently active scene. Only tracked scenes may be assigned.

DuplicateLoadPolicy

(DuplicateSceneLoadPolicy) { get; set } = DuplicateSceneLoadPolicy.ReuseExisting: Gets or sets the policy that controls how duplicate scene loads are handled.

PersistentRoot

(Node) = new() { Name = "PersistentRoot" }: Gets the root node that persists across all scene loads and unloads.

Public Methods

LoadNodeAsync

public Task<Node> LoadNodeAsync(Guid assetId)

Parameters:

  • assetId (Guid)

Returns: Task<Node>

LoadSceneAsync

public async Task<LoadedScene> LoadSceneAsync(Guid sceneAssetId, LoadSceneMode mode = LoadSceneMode.Single)

Parameters:

  • sceneAssetId (Guid)
  • mode (LoadSceneMode) (Default: LoadSceneMode.Single)

Returns: Task<LoadedScene>

AdoptScene

public LoadedScene AdoptScene(Guid sceneAssetId, Node root, LoadSceneMode mode = LoadSceneMode.Single)

Parameters:

  • sceneAssetId (Guid)
  • root (Node)
  • mode (LoadSceneMode) (Default: LoadSceneMode.Single)

Returns: LoadedScene

TryGetLoadedScene

public bool TryGetLoadedScene(Guid sceneAssetId, LoadedScene? scene)

Parameters:

  • sceneAssetId (Guid)
  • scene (LoadedScene?)

Returns: bool

SetActiveScene

public bool SetActiveScene(LoadedScene scene)

Parameters:

  • scene (LoadedScene)

Returns: bool

InstantiateAsync

public async Task<Node> InstantiateAsync(Guid sceneAssetId, Node? parent = null)

Parameters:

  • sceneAssetId (Guid)
  • parent (Node?) (Default: null)

Returns: Task<Node>

UnloadScene

public void UnloadScene(LoadedScene scene)

Parameters:

  • scene (LoadedScene)

UnloadAllScenes

public void UnloadAllScenes()

EnsureScenesStarted

public void EnsureScenesStarted()

Ensures the deferred start phase is executed once for every tracked scene.

Remarks: Called once per frame by the game loop, after any in-flight scene load has completed. Safe to call when no scenes are loaded.