Skip to content

t1k:unity:base:scene-management

FieldValue
Modulebase
Version5.116.6
Effortmedium
Tools—

Keywords: loading, scene, scene management

/t1k:unity:base:scene-management

Unity Scene Management — Loading, Transitions & Architecture

Section titled “Unity Scene Management — Loading, Transitions & Architecture”

Scene management reference for Unity 6. For DOTS SubScenes, see t1k-unity-dots-core-ecs.

using UnityEngine.SceneManagement;
SceneManager.LoadScene("GameLevel"); // Sync by name
SceneManager.LoadScene(1); // By build index
SceneManager.LoadScene("UI_Overlay", LoadSceneMode.Additive); // Keep current scene

All scenes must be added to File → Build Settings.

AsyncOperation op = SceneManager.LoadSceneAsync(sceneName);
op.allowSceneActivation = false; // Hold at 90% until ready
while (op.progress < 0.9f) yield return null;
op.allowSceneActivation = true;

Gotcha: progress caps at 0.9 when allowSceneActivation = false — this is intentional.

→ See references/scene-patterns.md for full loading-bar coroutine, additive patterns, event callbacks.

Bootstrap.unity (index 0) → loads Persistent.unity (additive, never unloads)
→ loads MainMenu.unity (additive)
→ unloads Bootstrap

Use additive scenes for: UI layers, audio managers, lighting, gameplay zones.

→ See references/scene-patterns.md for Bootstrap code, DontDestroyOnLoad pattern, fade transition.

SceneManager.sceneLoaded += OnSceneLoaded;
SceneManager.sceneUnloaded += OnSceneUnloaded;
SceneManager.activeSceneChanged += OnActiveSceneChanged;
// Always unsubscribe in OnDisable
  1. Scene not in Build Settings: a scene missing from Build Settings does not load; LoadScene does not throw (managed source has no throw/status check) — add the scene to Build Settings and verify with SceneUtility.GetBuildIndexByScenePath / the Editor console; do not assume a log line
  2. Static references survive: Reset static variables manually on scene load
  3. Additive scene lighting: Each scene bakes own lightmaps — use one lighting scene
  4. FindObjectOfType: Searches ALL loaded scenes — be explicit
  5. A PrefabInstance with a dangling m_SourcePrefab GUID materialises NO GameObject, silently: if that instance was the scene’s only Main Camera, the scene has ZERO cameras at runtime and renders nothing — no console error. Observed in DOTSTemplate-derived projects (1.MainScene.unity); a camera in a previous scene doesn’t save you since single-mode loads unload it. scene.GetRootGameObjects() can’t find it because there’s no GameObject to find — grep the scene YAML for m_SourcePrefab: {fileID: 100100000, guid: ...} and confirm each GUID resolves to a .meta on disk, or just count Camera components after load.
  • t1k-unity-base-addressables — Addressable scene loading
  • t1k-unity-audio-core — Persistent audio across scenes
  • t1k-unity-dots-core-ecs — DOTS SubScenes (use t1k-unity-dots-core-implementer agent)
  • t1k-unity-dots-nav-battlefield — Scene setup (use t1k-unity-dots-core-environment agent)
FileContents
references/scene-patterns.mdFull code: async loading, additive, events, bootstrap, fade transition, gotchas