SceneGraph

ScriptableObject asset that holds the complete set of scene nodes for the project. Acts as the single source of truth for scene registration and dependency relationships. Implements IEnumerable<Scene> for LINQ-friendly iteration.

Definition

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

public class SceneGraph : ParagonScriptableObject, IEnumerable<Scene>

Inheritance: ScriptableObject → ParagonScriptableObject → SceneGraph Implements: IEnumerable<Scene>

Remarks

SceneGraph is the central registry for the SceneManagement system. Every scene used by the game must be added to a SceneGraph asset. At runtime, the SceneManager loads the SceneGraph from Resources and uses it for all scene lookups, dependency chain resolution, and load/unload operations.

Internal Storage

Scenes are stored as a List<SceneNode> using [SerializeReference]. Each SceneNode wraps a Scene and maintains its own dependency list. When a scene is removed, the graph also removes it from all other nodes' dependency lists to maintain graph integrity.

Enumeration

SceneGraph implements IEnumerable<Scene>, allowing direct iteration over all registered scenes without exposing the internal SceneNode list:

foreach (Scene scene in sceneGraph)
{
    Debug.Log(scene.Name);
}

// LINQ works too
Scene found = sceneGraph.FirstOrDefault(s => s.Name == "MainMenu");

Quick Lookup

Goal	How
Add a scene	sceneGraph.AddScene(scene)
Remove a scene	sceneGraph.RemoveScene(scene)
Get a node	sceneGraph.GetSceneNode(scene)
Get all scenes	sceneGraph.GetAllScenes() or foreach
Get scene count	sceneGraph.Count
Check if contains scene	sceneGraph.Contains(scene) (via LINQ)
Clear all scenes	sceneGraph.Reset()

Properties

Property	Type	Access	Description
Count	int	public	Number of scene nodes in the graph

Fields

Field	Type	Access	Description
scenes	List<SceneNode>	private	Internal list of scene nodes ([SerializeReference])

Constructors

SceneGraph()

Private constructor. Initializes the scenes list. SceneGraph instances are created as ScriptableObject assets via Unity's asset creation workflow.

private SceneGraph()

Methods

AddScene

Adds a new scene to the graph. Logs an error if the scene already exists.

public void AddScene(Scene scene)

Parameter	Type	Description
scene	Scene	The scene to register

Behavior:

• If a SceneNode with the same Scene already exists, logs "Scene {name} already exists in the graph." and returns

• Otherwise, creates a new SceneNode(this, scene) and appends it to the list

RemoveScene

Removes a scene and cleans up all dependency references to it across the graph.

public void RemoveScene(Scene scene)

Parameter	Type	Description
scene	Scene	The scene to remove

Behavior:

1. Finds the SceneNode matching the scene

2. If not found, returns silently

3. Removes the node from the list

4. Iterates all remaining nodes and calls RemoveDependency(node) on each to remove dangling references

GetSceneNode

Returns the SceneNode for a given scene, or null if not found.

public SceneNode GetSceneNode(Scene scene)

Parameter	Type	Description
scene	Scene	The scene to look up

Returns: The matching SceneNode, or null.

GetAllScenes

Returns all scenes in the graph as a flat enumerable.

public IEnumerable<Scene> GetAllScenes()

Returns: An IEnumerable<Scene> projected from the internal node list.

GetEnumerator

Implements IEnumerable<Scene>. Delegates to GetAllScenes().GetEnumerator().

public IEnumerator<Scene> GetEnumerator()

Reset

Clears all scene nodes from the graph.

public void Reset()

Common Pitfalls

Duplicate scenes are rejected AddScene checks for duplicates by Scene equality (path + name + GUID). If you attempt to add the same scene twice, an error is logged and the call is a no-op. To update a scene, remove it first, then re-add.

RemoveScene cascades to dependencies When a scene is removed, it is also removed from the dependency list of every other node. This prevents dangling references but may silently break expected dependency chains if the removed scene was a prerequisite for others.

SceneGraph must be in Resources at runtime The SceneManager.Initialize() method loads the SceneGraph via Resources.FindObjectsOfTypeAll<SceneGraph>() in non-editor builds. Ensure the asset is placed where it can be discovered at runtime.

Private constructor — ScriptableObject creation only Do not attempt to instantiate SceneGraph via new. Use ScriptableObject.CreateInstance<SceneGraph>() or Unity's asset creation menu.

Examples

Building a Scene Graph (Editor)

#if UNITY_EDITOR
using UnityEditor;
using Paragon.Core.SceneManagement;

// Create the asset
var graph = ScriptableObject.CreateInstance<SceneGraph>();
AssetDatabase.CreateAsset(graph, "Assets/Resources/SceneGraph.asset");

// Add scenes
Scene mainMenu = new Scene(AssetDatabase.LoadAssetAtPath<SceneAsset>("Assets/Scenes/MainMenu.unity"));
Scene sharedUI = new Scene(AssetDatabase.LoadAssetAtPath<SceneAsset>("Assets/Scenes/SharedUI.unity"));
Scene gameLevel = new Scene(AssetDatabase.LoadAssetAtPath<SceneAsset>("Assets/Scenes/GameLevel01.unity"));

graph.AddScene(mainMenu);
graph.AddScene(sharedUI);
graph.AddScene(gameLevel);

// Set up dependencies
SceneNode gameLevelNode = graph.GetSceneNode(gameLevel);
gameLevelNode.AddDependency(sharedUI);

EditorUtility.SetDirty(graph);
AssetDatabase.SaveAssets();
#endif

Querying the Graph

using Paragon.Core.SceneManagement;
using System.Linq;

// Iterate all scenes
foreach (Scene scene in sceneGraph)
{
    Debug.Log($"Registered: {scene.Name}");
}

// Find by name (LINQ)
Scene found = sceneGraph.FirstOrDefault(s => s.Name == "MainMenu");

// Check count
Debug.Log($"Total scenes: {sceneGraph.Count}");

See Also

• Scene — the scene reference stored in each node

• SceneNode — graph node with dependency tracking

• SceneManager — static API that operates on the graph

• SceneManagement Overview — system overview