ISceneManager

Provides centralized scene and prefab loading, scene lifecycle management, active-scene switching, and hierarchy instantiation operations.

Remarks

Implementations are expected to be driven from the game loop's thread. A single SceneManager instance services both scene and prefab operations since scenes and prefabs share the same serialized node-hierarchy format.

Properties

LoadedScenes

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

ActiveScene

(LoadedScene?) { get; set }: Gets or sets the currently active scene. Implementations must reject values that are not currently tracked by the scene manager.

DuplicateLoadPolicy

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

PersistentRoot

(Node) : Gets the root node that persists across all scene loads and unloads.

Public Methods

LoadNodeAsync

 Task<Node> LoadNodeAsync(Guid assetId)

Loads and deserializes a node hierarchy from the asset database without attaching it to the loaded scene list.

Parameters:

  • assetId (Guid): The unique identifier of the prefab or scene asset to load.

Returns: Task<Node>

  • A task that represents the asynchronous operation, containing the loaded root node.

LoadNodeAsync

 Task<Node> LoadNodeAsync(string absolutePath)

Loads and deserializes a node hierarchy from an absolute file path without attaching it to the loaded scene list.

Parameters:

  • absolutePath (string): The absolute path to the serialized node file.

Returns: Task<Node>

  • A task that represents the asynchronous operation, containing the loaded root node.

LoadSceneAsync

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

Asynchronously loads a scene from the specified asset. Duplicate handling is controlled by DuplicateLoadPolicy. Single-mode loads unload all currently tracked scenes before loading the new scene, unless the implementation reuses an already loaded matching scene.

Parameters:

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

Returns: Task<LoadedScene>

LoadSceneAsync

 Task<LoadedScene> LoadSceneAsync(string absolutePath, LoadSceneMode mode = LoadSceneMode.Single)

Loads a scene from disk and tracks it as a loaded scene. The scene is keyed by a deterministic hash of the absolute path so that TryGetLoadedScene can find it on subsequent calls.

Parameters:

  • absolutePath (string)
  • mode (LoadSceneMode) (Default: LoadSceneMode.Single)

Returns: Task<LoadedScene>

AdoptScene

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

Tracks an already-deserialized hierarchy as a loaded scene, without reading it from disk. The adopted scene becomes the active scene.

Parameters:

  • sceneAssetId (Guid): The identifier to track the scene under.
  • root (Node): The root node of the hierarchy to adopt.
  • mode (LoadSceneMode): Whether to unload the currently tracked scenes first. (Default: LoadSceneMode.Single)

Returns: LoadedScene

Remarks: Used by the Studio's play mode, which runs on an in-memory copy of the scene being edited rather than on the last version written to disk.

TryGetLoadedScene

 bool TryGetLoadedScene(Guid sceneAssetId, LoadedScene? scene)

Attempts to find a tracked loaded scene by asset identifier.

Parameters:

  • sceneAssetId (Guid)
  • scene (LoadedScene?)

Returns: bool

SetActiveScene

 bool SetActiveScene(LoadedScene scene)

Sets the currently active scene.

Parameters:

  • scene (LoadedScene)

Returns: bool

SetActiveScene

 bool SetActiveScene(Guid sceneAssetId)

Sets the currently active scene by asset identifier.

Parameters:

  • sceneAssetId (Guid)

Returns: bool

InstantiateAsync

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

Instantiates a prefab or scene hierarchy under the provided parent node. If parent is null, the instantiated root is attached to the active scene root when available.

Parameters:

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

Returns: Task<Node>

InstantiateAsync

 Task<Node> InstantiateAsync(AssetReference<Prefab> assetReference, Node? parent = null)

Instantiates a prefab or scene hierarchy referenced by an asset reference. If parent is null, the instantiated root is attached to the active scene root when available.

Parameters:

  • assetReference (AssetReference)
  • parent (Node?) (Default: null)

Returns: Task<Node>

Remarks: For type-safe instantiation that returns a specific component on the instantiated root, declare the field as PrefabReference&lt;TComponent&gt; and call its InstantiateAsync method instead of this overload.

InstantiateAsync

 Task<Node> InstantiateAsync(string absolutePath, Node? parent = null)

Instantiates a prefab or scene hierarchy from disk under the provided parent node.

Parameters:

  • absolutePath (string)
  • parent (Node?) (Default: null)

Returns: Task<Node>

InstantiateAsync

 Task<T> InstantiateAsync(T componentTemplate, Node? parent = null)

Clones the hierarchy that owns the given attached component and returns the corresponding component on the cloned tree. This overload is only valid for components currently attached to a live scene hierarchy; detached templates must instead be loaded via a PrefabReference&lt;TComponent&gt;.

Parameters:

  • componentTemplate (T)
  • parent (Node?) (Default: null)

Returns: Task<T>

UnloadScene

 void UnloadScene(LoadedScene scene)

Unloads the specified scene and cleans up its resources.

Parameters:

  • scene (LoadedScene)

UnloadScene

 bool UnloadScene(Guid sceneAssetId)

Unloads a tracked scene by asset identifier.

Parameters:

  • sceneAssetId (Guid)

Returns: bool

UnloadAllScenes

 void UnloadAllScenes()

Unloads all currently loaded scenes.

EnsureScenesStarted

 void EnsureScenesStarted()

Runs the deferred Start phase once for every tracked scene. Expected to be invoked at the start of every game-loop tick.