SceneManager

Static facade wrapping Unity's SceneManager with dependency-aware scene loading. Resolves dependency chains from the SceneGraph and loads prerequisite scenes automatically before the target scene. Supports both synchronous and async loading, and fires events for scene load/unload.

Definition

Namespace: Paragon.Core.SceneManagement Assembly: Paragon.dll

public class SceneManager

Remarks

SceneManager is the primary API for scene operations in the Paragon framework. It wraps Unity's UnityEngine.SceneManagement.SceneManager and adds dependency chain resolution via the SceneGraph.

Initialization

The class auto-initializes via [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]. In non-editor builds, it discovers the SceneGraph via Resources.FindObjectsOfTypeAll<SceneGraph>(). It also subscribes to Unity's sceneLoaded and sceneUnloaded callbacks to translate them into Paragon Scene-typed events.

Dependency Chain Loading

When loadDependencies is true (the default), LoadScene and LoadSceneAsync call GetDependencyChain() to perform an iterative depth-first search (DFS) that produces a topologically ordered list of dependencies. Dependencies are loaded before the target scene.

The DFS algorithm:

1. Pushes the target scene's node onto a stack

2. For each node, pushes unvisited dependencies (in reverse order) onto the stack

3. When a node has no more unvisited dependencies, it is popped and added to the result set

4. This produces a post-order traversal — dependencies appear before dependents

Load Scene Mode

After loading the first dependency (or the target scene if there are no dependencies), the mode is forced to ADDITIVE for all subsequent loads in the chain. When the original mode is SINGLE, the target scene is set as the active scene once loading completes.

Quick Lookup

Goal	How
Load scene (sync)	SceneManager.LoadScene(scene)
Load scene (async)	await SceneManager.LoadSceneAsync(scene)
Unload scene (sync)	SceneManager.UnloadScene(scene)
Unload scene (async)	await SceneManager.UnloadSceneAsync(scene)
Load with dependencies	SceneManager.LoadScene(scene, loadDependencies: true) (default)
Load without dependencies	SceneManager.LoadScene(scene, loadDependencies: false)
Load additively	SceneManager.LoadScene(scene, loadSceneMode: LoadSceneMode.ADDITIVE)
Get active scene	SceneManager.GetActiveScene()
Set active scene	SceneManager.SetActiveScene(scene)
Check if loaded	SceneManager.IsSceneLoaded(scene)
Get all loaded scenes	SceneManager.GetLoadedScenes()
Look up scene by name	SceneManager.GetScene("MyScene")
Look up scene by path	SceneManager.GetScene("Assets/Scenes/MyScene.unity")
Move object to scene	SceneManager.MoveGameObjectToScene(go, scene)
Move object to active scene	SceneManager.MoveGameObjectToActiveScene(go)
Listen for loads	SceneManager.SceneLoaded += handler
Listen for unloads	SceneManager.SceneUnloaded += handler

Fields

Field	Type	Access	Description
sceneGraph	SceneGraph	protected static	The scene graph used for lookups and dependency resolution

Events

Event	Type	Description
SceneLoaded	Action<Scene>	Fired after a scene finishes loading (maps from Unity's sceneLoaded callback)
SceneUnloaded	Action<Scene>	Fired after a scene is unloaded (maps from Unity's sceneUnloaded callback)

Methods

LoadScene

Loads a scene synchronously with optional dependency chain resolution.

public static void LoadScene(Scene scene, bool loadDependencies = true, LoadSceneMode loadSceneMode = LoadSceneMode.SINGLE)

Parameter	Type	Default	Description
scene	Scene	—	The target scene to load
loadDependencies	bool	true	Whether to load dependency scenes first
loadSceneMode	LoadSceneMode	SINGLE	SINGLE unloads current scenes; ADDITIVE keeps them

Behavior:

1. If loadDependencies is true, resolves the dependency chain (excluding the target) and loads each in order

2. After loading dependencies, forces mode to ADDITIVE for subsequent loads

3. Loads the target scene

4. If original mode was SINGLE, subscribes to SceneLoaded to call SetActiveScene when the target finishes loading

LoadSceneAsync

Loads a scene asynchronously with optional dependency chain resolution. Returns a Task that completes when all scenes (dependencies + target) finish loading.

public static async Task LoadSceneAsync(Scene scene, bool loadDependencies = true, LoadSceneMode loadSceneMode = LoadSceneMode.SINGLE)

Parameter	Type	Default	Description
scene	Scene	—	The target scene to load
loadDependencies	bool	true	Whether to load dependency scenes first
loadSceneMode	LoadSceneMode	SINGLE	SINGLE unloads current scenes; ADDITIVE keeps them

Behavior:

1. Starts all dependency load operations and collects AsyncOperation handles

2. Starts the target scene load operation

3. Awaits all operations via Yield.WaitUntil(() => all.isDone)

4. If original mode was SINGLE, sets the target as the active scene

UnloadScene

Unloads a scene. Wraps UnloadSceneAsync with async void.

public static async void UnloadScene(Scene scene, bool unloadDependencies = false)

Parameter	Type	Default	Description
scene	Scene	—	The scene to unload
unloadDependencies	bool	false	Whether to also unload dependency scenes

UnloadSceneAsync

Unloads a scene asynchronously. Returns a Task that completes when all unload operations finish.

public static async Task UnloadSceneAsync(Scene scene, bool unloadDependencies = false)

Parameter	Type	Default	Description
scene	Scene	—	The scene to unload
unloadDependencies	bool	false	Whether to also unload dependency scenes

GetDependencyChain

Performs an iterative DFS to compute the full dependency chain for a scene, in topological order (dependencies first).

protected static IEnumerable<Scene> GetDependencyChain(Scene scene)

Parameter	Type	Description
scene	Scene	The root scene to resolve dependencies for

Returns: An IEnumerable<Scene> containing all dependencies plus the target scene, in load order. The target scene appears last.

MoveGameObjectToScene

Moves a GameObject to the specified scene.

public static void MoveGameObjectToScene(GameObject gameObject, Scene scene)

MoveGameObjectToActiveScene

Moves a GameObject to the currently active scene.

public static void MoveGameObjectToActiveScene(GameObject gameObject)

GetActiveScene

Returns the currently active Scene.

public static Scene GetActiveScene()

SetActiveScene

Sets a loaded scene as the active scene.

public static void SetActiveScene(Scene scene)

GetLoadedScenes

Returns all scenes from the SceneGraph that are currently loaded.

public static IEnumerable<Scene> GetLoadedScenes()

IsSceneLoaded

Checks if a scene is currently loaded and valid.

public static bool IsSceneLoaded(Scene scene)

GetScene(string)

Looks up a scene by name or path. If the string contains '/', it matches by path; otherwise by name.

public static Scene GetScene(string sceneNameOrPath)

Returns: The matching Scene, or null if not found.

GetScene(UnityScene)

Looks up a Paragon Scene from a Unity scene, using the Unity scene's path.

public static Scene GetScene(UnityScene unityScene)

TryGetScene

Attempts to look up a scene by name or path.

public static bool TryGetScene(string sceneNameOrPath, out Scene scene)

Returns: true if the scene was found in the SceneGraph.

GetUnityScene

Converts a Paragon Scene to a Unity Scene by looking up the path.

public static UnityScene GetUnityScene(Scene scene)

Extension Points

Subclassing SceneManager

The sceneGraph field is protected static, allowing subclasses to provide custom graph initialization:

public class CustomSceneManager : SceneManager
{
    public static void SetGraph(SceneGraph graph)
    {
        sceneGraph = graph;
    }
}

The GetDependencyChain method is protected static, making it available to subclasses for custom loading logic.

Enums

LoadSceneMode

public enum LoadSceneMode
{
    SINGLE = UnityLoadSceneMode.Single,    // Unloads all current scenes
    ADDITIVE = UnityLoadSceneMode.Additive // Keeps current scenes loaded
}

Common Pitfalls

All scenes must be in the SceneGraph The OnSceneLoaded and OnSceneUnloaded callbacks throw NotSupportedException if the loaded/unloaded scene is not found in the SceneGraph. The only exception is Unity's built-in splash screen (buildIndex == -1), which is silently skipped during unload.

UnloadScene is async void UnloadScene uses async void, which means exceptions are unobservable. For error handling, prefer UnloadSceneAsync which returns a Task.

LoadScene forces ADDITIVE after first dependency When loading with dependencies and LoadSceneMode.SINGLE, the first dependency uses SINGLE mode (unloading current scenes), but all subsequent loads in the chain use ADDITIVE. This means the first dependency unloads everything, then the rest load additively on top. Be aware of this ordering when designing scene dependencies.

Dependency chain does not skip already-loaded scenes GetDependencyChain returns all dependencies regardless of whether they are already loaded. LoadScene does not check IsSceneLoaded before loading — it may reload already-loaded scenes depending on the mode.

Static state survives domain reload Events (SceneLoaded, SceneUnloaded) and the sceneGraph reference are static. In the editor with domain reload disabled, stale event subscriptions may persist. The [RuntimeInitializeOnLoadMethod(SubsystemRegistration)] attribute handles re-initialization, but events are not cleared automatically.

Examples

Load a Level with Dependencies

using Paragon.Core.SceneManagement;

// Loads SharedUI, then GameLevel01 (if SharedUI is a dependency)
SceneManager.LoadScene("GameLevel01");

Async Scene Transition

using Paragon.Core.SceneManagement;

public async void TransitionToLevel(string levelName)
{
    // Show loading screen additively
    SceneManager.LoadScene("LoadingScreen", loadDependencies: false, LoadSceneMode.ADDITIVE);

    // Load the target level asynchronously
    await SceneManager.LoadSceneAsync(levelName, loadDependencies: true);

    // Unload loading screen
    SceneManager.UnloadScene("LoadingScreen");
}

Listening to Scene Events

using Paragon.Core.SceneManagement;

private void OnEnable()
{
    SceneManager.SceneLoaded += OnSceneLoaded;
    SceneManager.SceneUnloaded += OnSceneUnloaded;
}

private void OnDisable()
{
    SceneManager.SceneLoaded -= OnSceneLoaded;
    SceneManager.SceneUnloaded -= OnSceneUnloaded;
}

private void OnSceneLoaded(Scene scene)
{
    Debug.Log($"Scene loaded: {scene.Name}");
}

private void OnSceneUnloaded(Scene scene)
{
    Debug.Log($"Scene unloaded: {scene.Name}");
}

Checking Scene Status

using Paragon.Core.SceneManagement;

// Check if a specific scene is loaded
if (SceneManager.IsSceneLoaded("GameLevel01"))
{
    Debug.Log("Level is active");
}

// Get all currently loaded scenes
foreach (Scene scene in SceneManager.GetLoadedScenes())
{
    Debug.Log($"Loaded: {scene.Name}");
}

See Also

• Scene — scene reference type used by all methods

• SceneGraph — the graph backing all scene lookups

• SceneNode — graph node with dependency data

• SceneManagement Overview — system overview