SceneManagement

The SceneManagement system provides a dependency-aware scene loading framework built on top of Unity's SceneManager. Scenes are organized into a directed acyclic graph (SceneGraph) where each node declares its dependencies, enabling automatic loading of prerequisite scenes in the correct order.

Architecture

Dependency Loading Flow

Classes

Class	Description
Scene	Serializable scene reference with path, name, and GUID; implicit conversion to/from string and UnityScene
SceneNode	Graph node linking a Scene with its dependency list
SceneGraph	ScriptableObject containing all SceneNode entries; provides add/remove/query operations
SceneManager	Static facade wrapping Unity's SceneManager with dependency chain resolution and async loading

Enums

Enum	Values	Description
LoadSceneMode	SINGLE, ADDITIVE	Maps to Unity's LoadSceneMode — controls whether existing scenes are unloaded

Quick Start

Define a Scene Graph (Editor)

Create a SceneGraph ScriptableObject asset. Add scenes via the editor or script:

// Editor context
sceneGraph.AddScene(new Scene(mySceneAsset));
sceneGraph.AddScene(new Scene(sharedUIAsset));

// Set up dependencies
SceneNode mainNode = sceneGraph.GetSceneNode(mainScene);
mainNode.AddDependency(sharedUIScene);

Load a Scene with Dependencies

using Paragon.Core.SceneManagement;

// Synchronous — loads all dependencies first, then the target scene
SceneManager.LoadScene("GameLevel01", loadDependencies: true);

// Async — returns Task, awaitable
await SceneManager.LoadSceneAsync("GameLevel01", loadDependencies: true);

// Additive — does not unload current scenes
SceneManager.LoadScene("HUD", loadDependencies: false, LoadSceneMode.ADDITIVE);

Listen for Scene Events

SceneManager.SceneLoaded += scene => Debug.Log($"Loaded: {scene.Name}");
SceneManager.SceneUnloaded += scene => Debug.Log($"Unloaded: {scene.Name}");

Implicit Conversions

// String to Scene (looks up in SceneGraph)
Scene scene = "GameLevel01";

// Scene to UnityScene
UnityEngine.SceneManagement.Scene unityScene = scene;

// UnityScene to Scene
Scene paragonScene = UnitySceneManager.GetActiveScene();

Key Concepts

Dependency Chain Resolution

The SceneManager.GetDependencyChain() method performs an iterative depth-first search (DFS) to produce a topologically ordered list of scenes. Dependencies are loaded before the target scene, ensuring prerequisite scenes are available when the target scene initializes.

SceneGraph as Single Source of Truth

All scene lookups (GetScene, TryGetScene, implicit operators) resolve against the SceneGraph. At runtime, the SceneGraph is loaded from Resources. Every scene used by the game must exist in the graph, or load/unload callbacks will throw NotSupportedException.

Editor/Runtime Sync

The Scene class uses ISerializationCallbackReceiver to keep the SceneAsset reference (editor-only) synchronized with the serialized scenePath, sceneName, and guid fields that persist at runtime.

See Also

• ParagonScriptableObject — base class for SceneGraph