scene-architecture

name	scene-architecture
description	Use when you need detailed decision frameworks for scene structure, additive loading, scene management, transitions, and persistent managers.

Scene Architecture — Full Decision Framework

Use this when unity-architect's condensed scene section needs more depth.

DECISION: Scene Organization Pattern

When this applies: Deciding how to split a game into scenes.

Options:

1. Monolithic (single scene) — entire game in one scene.

   • Use when: game jam, prototype, very small game (< 50 GameObjects total).
   • Tradeoff: cannot stream content, large file, merge conflicts in teams.

2. Scene-per-state — Menu scene, Game scene, Results scene, etc.

   • Use when: distinct game states with clean boundaries.
   • Tradeoff: need persistent managers (audio, network) that survive loads.
   • Transition: LoadScene (replaces) or LoadSceneAsync for loading screens.

3. Bootstrap + additive — one persistent scene + content scenes loaded/unloaded.

   • Use when: persistent UI, managers, or audio across multiple levels.
   • Tradeoff: more complex loading logic, must manage active scene.
   • Pattern: Bootstrap loads first (scene 0 in build), then loads content additively.

4. Streaming (additive + distance) — world divided into chunks loaded by proximity.

   • Use when: open world, large levels, seamless transitions.
   • Tradeoff: complex trigger system, memory management, cross-scene references impossible.

Decision tree:

Is the game small enough for one scene?
├── YES → Monolithic
└── NO → Are there persistent systems across states?
    ├── NO → Scene-per-state (simple LoadScene)
    └── YES → Bootstrap + additive
              └── Is the world large/seamless? → Streaming chunks

DECISION: Persistent Managers

When this applies: Systems that must survive scene transitions (audio, networking, input, game state).

Options:

1. Bootstrap scene (recommended) — managers live in a scene that is never unloaded.

   • Setup: Create a minimal scene with manager GameObjects. Set as scene 0 in build.
   • On start: bootstrap loads, then loads first content scene additively.
   • Benefit: managers are inspectable, debuggable, follow normal lifecycle.

2. DontDestroyOnLoad — mark specific GameObjects as persistent.

   • Use only when: you cannot control the initial scene load order.
   • Tradeoff: invisible in hierarchy after first load, confusing for new developers.
   • If you must: one root parent marked DDOL, all persistent objects as children.

3. Static classes — no GameObject, pure C# static state.

   • Use only when: data-only (no MonoBehaviour lifecycle needed).
   • Tradeoff: no Inspector visibility, no coroutines, no Update.

DECISION: Scene Transitions

When this applies: Moving between game states or levels.

Options:

1. Hard cut — LoadScene (non-async). Screen goes blank briefly.

   • Use when: transitions are instant and small (menu → settings and back).

2. Fade transition — full-screen UI fades in, load happens behind, fade out.

   • Use when: clean transition without showing loading.
   • Implementation: persistent Canvas with fade panel in bootstrap scene.

3. Loading screen — separate loading scene with progress bar.

   • Use when: loads take > 1 second, need to show progress.
   • Pattern: Load loading-scene additively → unload old content → async load new content → unload loading-scene.

MCP tool sequence for scene setup:

1. scene_create — create bootstrap scene.
2. scene_create_gameobject — create manager objects.
3. component_add — add manager scripts.
4. scene_create — create first content scene.
5. scene_set_build — register both in build settings, bootstrap at index 0.

Related Skills

• uniclaude:unity-architect — condensed scene decisions
• uniclaude:scene-authoring — MCP tool sequences for building scenes