t1k:unity:base:scene-management
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | medium |
| Tools | — |
Keywords: loading, scene, scene management
How to invoke
Section titled “How to invoke”/t1k:unity:base:scene-managementUnity 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.
Basic Loading
Section titled “Basic Loading”using UnityEngine.SceneManagement;
SceneManager.LoadScene("GameLevel"); // Sync by nameSceneManager.LoadScene(1); // By build indexSceneManager.LoadScene("UI_Overlay", LoadSceneMode.Additive); // Keep current sceneAll scenes must be added to File → Build Settings.
Async Loading
Section titled “Async Loading”AsyncOperation op = SceneManager.LoadSceneAsync(sceneName);op.allowSceneActivation = false; // Hold at 90% until readywhile (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 Architecture
Section titled “Bootstrap Architecture”Bootstrap.unity (index 0) → loads Persistent.unity (additive, never unloads) → loads MainMenu.unity (additive) → unloads BootstrapUse additive scenes for: UI layers, audio managers, lighting, gameplay zones.
→ See references/scene-patterns.md for Bootstrap code, DontDestroyOnLoad pattern, fade transition.
Key Callbacks
Section titled “Key Callbacks”SceneManager.sceneLoaded += OnSceneLoaded;SceneManager.sceneUnloaded += OnSceneUnloaded;SceneManager.activeSceneChanged += OnActiveSceneChanged;// Always unsubscribe in OnDisableHard rules
Section titled “Hard rules”- Scene not in Build Settings: a scene missing from Build Settings does not load;
LoadScenedoes not throw (managed source has no throw/status check) — add the scene to Build Settings and verify withSceneUtility.GetBuildIndexByScenePath/ the Editor console; do not assume a log line - Static references survive: Reset static variables manually on scene load
- Additive scene lighting: Each scene bakes own lightmaps — use one lighting scene
- FindObjectOfType: Searches ALL loaded scenes — be explicit
- A
PrefabInstancewith a danglingm_SourcePrefabGUID 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 form_SourcePrefab: {fileID: 100100000, guid: ...}and confirm each GUID resolves to a.metaon disk, or just countCameracomponents after load.
Related Skills & Agents
Section titled “Related Skills & Agents”t1k-unity-base-addressables— Addressable scene loadingt1k-unity-audio-core— Persistent audio across scenest1k-unity-dots-core-ecs— DOTS SubScenes (uset1k-unity-dots-core-implementeragent)t1k-unity-dots-nav-battlefield— Scene setup (uset1k-unity-dots-core-environmentagent)
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
references/scene-patterns.md | Full code: async loading, additive, events, bootstrap, fade transition, gotchas |