# Scene Flow — Complete Level Loading Architecture

**Game:** Project Void | **Build Phase:** 2
**Framework Systems:** 04_GI_GameFramework, 05_GM_CoreGameMode, 44_SS_UIManager, 110_BPC_LoadingScreen, 114_WBP_SplashScreen, 128_SS_EnhancedInputManager

---

## Purpose

This document defines every scene transition in the game — from engine boot to credits roll. It specifies what loads, what plays, what the player sees, and how control flows between levels. Use this as the definitive reference when wiring level transitions and testing scene flow.

---

## Complete Scene Map

```
                    ┌──────────────────────────────────────┐
                    │          GAME BOOT                    │
                    │  GI_HorrorGame.Init bootstraps       │
                    │  all SS_ subsystems, validates tags  │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 1: L_SplashScreen             │
                    │  Duration: ~8 seconds (skippable)     │
                    │  │  Studio Logo (2s, fade)            │
                    │  │  UE5 Logo (1.5s, fade)            │
                    │  │  "Project Void" Title (3s, fade)   │
                    │  │  Health Warning (1.5s, fade)       │
                    │  │  Audio: MS_MusicBus ambient_loop   │
                    │  └─ Auto-advance OR Skip →            │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 2: L_MainMenu                 │
                    │  │  3D Background: Asylum hallway     │
                    │  │  WBP_GameMainMenu displayed        │
                    │  │  ┌─────────────────────────┐      │
                    │  │  │ NEW GAME                │──────┤
                    │  │  │ CONTINUE (if save exists)│      │
                    │  │  │ LOAD GAME               │      │
                    │  │  │ SETTINGS                │      │
                    │  │  │ CREDITS                 │      │
                    │  │  │ QUIT                    │      │
                    │  │  └─────────────────────────┘      │
                    │  └────────────────────────────────────┘
                    │
                    ├─ NEW GAME ─────────────────────────────┐
                    │                                        │
                    ├─ CONTINUE ──────────────────────────┐  │
                    │                                     │  │
                    └─ SETTINGS ──────────────────┐       │  │
                                                   │       │  │
                                                   ▼       ▼  ▼
                              ┌──────────────────────────────────────┐
                              │  LOADING SCREEN (transitional)       │
                              │  │  WBP_LoadingHorror displayed      │
                              │  │  Progress bar + atmosphere tip    │
                              │  │  SS_SaveManager.ResetGameState()  │
                              │  │   (if New Game — fresh state)     │
                              │  │  SS_SaveManager.LoadSlot()        │
                              │  │   (if Continue/Load — restore)    │
                              │  │  GI_GameFramework.SetPhase        │
                              │  │   (Loading)                       │
                              │  │  Audio: Crossfade to target music │
                              │  └─ On level loaded → SetPhase(InGame)│
                              └──────────────┬───────────────────────┘
                                             │
                                             ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 3: L_Asylum_Entry (Tutorial)  │
                    │  │  Player wakes in padded cell       │
                    │  │  Opening cutscene: 3-5 seconds     │
                    │  │   (Camera pan, blur, voiceover)    │
                    │  │                                    │
                    │  │  Tutorial Sequence:                 │
                    │  │   1. Move/Look prompt               │
                    │  │   2. Interact: Pick up "Note"       │
                    │  │   3. Crouch: Navigate vent          │
                    │  │   4. Hide: First patient sighting   │
                    │  │   5. Objective: "Find a way out"    │
                    │  │                                    │
                    │  │  First Checkpoint: Safe Room        │
                    │  │  First Item: Flashlight (on desk)   │
                    │  │  First Door: Unlocked (tutorial)    │
                    │  │                                    │
                    │  │  Atmosphere: Light tension           │
                    │  │  Audio: Ward ambience, creaks       │
                    │  │  Difficulty: Tutorial (easy)         │
                    │  │                                    │
                    │  └─ Exit door → TransitionToChapter    │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 4: L_Asylum_WardA             │
                    │  │  Main Ward Area                    │
                    │  │                                    │
                    │  │  Objectives:                        │
                    │  │   • Find flashlight (if missed)     │
                    │  │   • Find pistol (security office)   │
                    │  │   • Restore power (fusebox puzzle)  │
                    │  │   • Find Keycard Alpha (nurses st.) │
                    │  │                                    │
                    │  │  Enemies:                           │
                    │  │   • 2-3 Patient enemies (patrol)    │
                    │  │   • Optional: Shade teaser (window) │
                    │  │                                    │
                    │  │  Puzzles:                           │
                    │  │   • BP_Puzzle_Fusebox              │
                    │  │     └─ Restore 3 circuit breakers   │
                    │  │     └─ Opens locked treatment room  │
                    │  │                                    │
                    │  │  Hiding Spots:                      │
                    │  │   • Lockers (3), Under Bed (2)      │
                    │  │                                    │
                    │  │  Collectibles:                      │
                    │  │   • 2 Patient Files, 1 Old Photo    │
                    │  │                                    │
                    │  │  Checkpoints:                       │
                    │  │   • Safe Room (start of area)        │
                    │  │   • Nurse Station Mirror             │
                    │  │                                    │
                    │  │  Atmosphere: Tension building        │
                    │  │  Audio: WardA acoustic preset       │
                    │  │  Scares: 2 (locker bang, whisper)   │
                    │  │                                    │
                    │  └─ Alpha Door → WardB                 │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 5: L_Asylum_WardB             │
                    │  │  High-Security Ward                 │
                    │  │                                    │
                    │  │  Objectives:                        │
                    │  │   • Find shotgun (morgue)           │
                    │  │   • Solve pipe organ puzzle         │
                    │  │   • Retrieve patient records        │
                    │  │   • Find Keycard Beta               │
                    │  │                                    │
                    │  │  Enemies:                           │
                    │  │   • 2-3 Orderly enemies (fast)      │
                    │  │   • 1-2 Patient enemies             │
                    │  │   • First Shade encounter (script)  │
                    │  │                                    │
                    │  │  First Void Shift:                   │
                    │  │   • Trigger: Enter morgue           │
                    │  │   • Effect: Walls bleed, corridor   │
                    │  │     loops, whispers intensify       │
                    │  │   • Duration: 30 seconds            │
                    │  │   • Exit: Find mirror and interact  │
                    │  │                                    │
                    │  │  Puzzles:                           │
                    │  │   • BP_Puzzle_PipeOrgan             │
                    │  │     └─ Play 4-note melody sequence  │
                    │  │     └─ Opens hidden chapel room     │
                    │  │                                    │
                    │  │  Collectibles:                      │
                    │  │   • 3 Patient Files, 1 Void Shard   │
                    │  │                                    │
                    │  │  Atmosphere: Horror ramping          │
                    │  │  Audio: WardB preset (darker, echo)  │
                    │  │  Scares: 3 (mirror face, window     │
                    │  │    slam, breathing behind player)    │
                    │  │                                    │
                    │  └─ Beta Door → Basement               │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 6: L_Asylum_Basement          │
                    │  │  Dark Horror Zone                   │
                    │  │                                    │
                    │  │  Special Rule: NO ambient light     │
                    │  │   • Player MUST use flashlight     │
                    │  │   • Battery management critical    │
                    │  │   • Flashlight attracts enemies    │
                    │  │                                    │
                    │  │  Objectives:                        │
                    │  │   • Find Warden's Key (morgue #4)   │
                    │  │   • Solve morgue drawer puzzle     │
                    │  │   • Survive Shade pursuit          │
                    │  │   • Escape basement via elevator    │
                    │  │                                    │
                    │  │  Enemies:                           │
                    │  │   • Shade (persistent, teleporting) │
                    │  │   • 2-3 Patient enemies (lost)      │
                    │  │                                    │
                    │  │  Stress System Peaks:               │
                    │  │   • Constant darkness = +stress     │
                    │  │   • Shade proximity = +stress       │
                    │  │   • At Critical: hallucinations     │
                    │  │     └─ False enemies, voices,       │
                    │  │        environment warps            │
                    │  │                                    │
                    │  │  Atmosphere: Maximum horror          │
                    │  │  Audio: Basement preset (reverb,     │
                    │  │    dripping water, distant screams)  │
                    │  │  Scares: 4+ (multiple jump scares)  │
                    │  │                                    │
                    │  └─ Elevator → Warden's Office         │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 7: L_Asylum_WardensOffice     │
                    │  │  Climax Area                        │
                    │  │                                    │
                    │  │  Objectives:                        │
                    │  │   • Read Warden's journal           │
                    │  │     └─ Reveals truth: asylum is     │
                    │  │       a psychic prison for an        │
                    │  │       eldritch entity               │
                    │  │   • Confront the truth              │
                    │  │     └─ Dialogue choice with entity  │
                    │  │     └─ Accept / Resist / Sacrifice  │
                    │  │                                    │
                    │  │  Ending Accumulator evaluates:      │
                    │  │   • VoidShards collected: 0 1 2 3   │
                    │  │   • Survivor NPC saved? Y/N         │
                    │  │   • Sanity at end: Low/Med/High     │
                    │  │   • Dialogue choice made            │
                    │  │   → Determines 3 possible endings   │
                    │  │                                    │
                    │  │  Atmosphere: Resolution/Tension      │
                    │  │  Audio: Final confrontation theme    │
                    │  └─ Ending trigger → L_Ending_Truth    │
                    └──────────────┬───────────────────────┘
                                   │
                     ┌─────────────┼─────────────┐
                     │             │             │
                     ▼             ▼             ▼
            ┌────────────┐ ┌────────────┐ ┌────────────┐
            │ ENDING A   │ │ ENDING B   │ │ ENDING C   │
            │ "Escape"   │ │ "Merge"    │ │ "Sacrifice"│
            │            │ │            │ │            │
            │ You resist │ │ You accept │ │ You sacri- │
            │ the entity │ │ the entity │ │ fice your- │
            │ and flee   │ │ and become │ │ self to    │
            │ the asylum │ │ its vessel  │ │ seal the   │
            │            │ │            │ │ entity     │
            │ Cutscene:  │ │ Cutscene:  │ │ Cutscene:  │
            │ Running    │ │ The asylum  │ │ You walk   │
            │ through    │ │ calms. The  │ │ into the   │
            │ collapsing │ │ entity      │ │ void. Light │
            │ halls.     │ │ speaks      │ │ fades.     │
            │ Daylight.  │ │ through you.│ │ Credits.   │
            └─────┬──────┘ └─────┬──────┘ └─────┬──────┘
                  │              │              │
                  └──────────────┼──────────────┘
                                 │
                                 ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 8: L_Ending_Truth             │
                    │  │  Closing cinematic plays           │
                    │  │  Post-credit scene (5s)            │
                    │  │                                    │
                    │  │  Achievement Unlocks:               │
                    │  │   • "Escaped the Void" (any ending) │
                    │  │   • Ending-specific achievement    │
                    │  │   • "Collector" (all VoidShards)    │
                    │  │   • "Pacifist" (killed 0 enemies)   │
                    │  └─ Auto-advance → L_Credits          │
                    └──────────────┬───────────────────────┘
                                   │
                                   ▼
                    ┌──────────────────────────────────────┐
                    │  SCENE 9: L_Credits                  │
                    │  │  Scroll credits (30-45 seconds)    │
                    │  │  Post-credit: WBP_DeathScreen      │
                    │  │   shows stats:                     │
                    │  │   • Total deaths, time, ending     │
                    │  │   • Collectibles found             │
                    │  │   • Ending classification          │
                    │  │                                    │
                    │  │  Button: "Return to Main Menu"     │
                    │  │  Button: "New Game+" (if unlocked) │
                    │  └─ Return → L_MainMenu               │
                    └──────────────────────────────────────┘
```

---

## Sub-Scenes: Pause, Death, Void Space

These can trigger from **any gameplay scene** (Scenes 3-7):

### Pause Branch

```
PRESS ESC (IA_PauseMenu) — any gameplay scene
   │
   ├─ PC_HorrorController → OpenPauseMenu
   │
   ├─ SS_UIManager.PushMenu(PauseMenu)
   │    ├─ Game Paused (SetPhase = Paused)
   │    ├─ SS_EnhancedInputManager.SetInputModeUIOnly()
   │    ├─ Mouse cursor shown
   │    ├─ WBP_HUDController hides diegetic HUD
   │    └─ WBP_GamePauseMenu displayed
   │
   ├─ Pause Menu Options:
   │    ├─ RESUME → PopMenu → SetPhase(InGame) → restore
   │    ├─ SAVE → SS_SaveManager.CreateManualSave
   │    ├─ LOAD → Push LoadGameMenu → select slot → load
   │    ├─ SETTINGS → PushMenu(SettingsMenu)
   │    ├─ RETURN TO MENU → Confirm → QuitToMenu
   │    └─ QUIT TO DESKTOP → Confirm → GI_HorrorGame.QuitToDesktop
   │
   └─ On Resume:
        ├─ SS_UIManager.PopMenu
        ├─ GI_GameFramework.SetGamePhase(InGame)
        ├─ SS_EnhancedInputManager.SetInputModeGameOnly()
        ├─ Mouse cursor hidden
        └─ WBP_HUDController shows diegetic HUD
```

### Death Branch (Normal)

```
PLAYER HEALTH = 0 — any gameplay scene
   │
   ├─ BPC_DeathHandlingSystem triggers
   │    ├─ Death animation plays (GASP death montage)
   │    ├─ BPC_StateManager.ForcePushState(Death)
   │    ├─ WBP_ScreenEffectController → Death fade-out
   │    └─ Audio: Death sting → silence
   │
   ├─ GM_HorrorGameMode.HandlePlayerDead
   │    │
   │    ├─ Check Void Space conditions (see below)
   │    │    └─ NOT void-qualified → Normal Respawn
   │    │
   │    └─ [Respawn Flow]
   │         ├─ Increment PS_HorrorPlayerState.DeathsThisChapter
   │         ├─ BPC_PersistentCorpseSystem.LeaveCorpse()
   │         ├─ BPC_RunHistoryTracker.LogDeath()
   │         ├─ BPC_PersistentWorldStateRecorder.SaveWorldState()
   │         ├─ SS_SaveManager.CreateAutoSave("DeathRespawn")
   │         │
   │         ├─ [If ALLOWED_DEATHS exceeded → Game Over option]
   │         │    ├─ Prompt: "Return to Main Menu?"
   │         │    └─ Yes → L_MainMenu, No → respawn anyway
   │         │
   │         └─ TransitionToChapter(LastCheckpointChapter)
   │              ├─ Loading screen
   │              └─ On loaded: BPC_PlayerRespawnSystem.RestoreState()
   │                   ├─ Health restored (checkpoint value)
   │                   ├─ Inventory restored (minus lost items)
   │                   ├─ World state restored (doors, items, enemies)
   │                   └─ WBP_ScreenEffectController → respawn fade-in
```

### Void Space Branch (Special Death)

```
TRIGGER: Death cause = "Void" AND first void death
  OR: Walk into void portal in Basement
   │
   ├─ GM_HorrorGameMode sets bVoidSpaceActive = true
   ├─ BPC_AltDeathSpaceSystem.EnterVoidSpace()
   │    ├─ TransitionToChapter(Chapter.VoidSpace)
   │    └─ Load L_Asylum_VoidSpace
   │
   └─ [Void Space Level]
        │
        ├─ Environment:
        │    ├─ Inverted lighting (black fog, white shadows)
        │    ├─ Geometry: Floating, non-Euclidean rooms
        │    ├─ Audio: Reversed whispers, heartbeat bass
        │    └─ No map/HUD — disoriented
        │
        ├─ Objective: "Find the light. Escape the void."
        │    ├─ Navigate shifting corridors
        │    ├─ Solve void puzzle (3 memory shrines)
        │    └─ Reach exit portal → return to real asylum
        │
        ├─ On Exit:
        │    ├─ BPC_AltDeathSpaceSystem.ExitVoidSpace()
        │    ├─ TransitionToChapter(ReturnChapter)
        │    │    └─ Return to where player died (or nearby)
        │    ├─ GI_HorrorGame.SetSessionFlag("VoidSpaceVisited", true)
        │    ├─ Player gains "Void Touched" status:
        │    │    └─ Can now see hidden void objects in real world
        │    └─ Health/Inventory restored to pre-death state
        │
        └─ Achievement: "Touched the Void"
```

---

## Loading Screen Specification

Used between every scene transition. Implemented by `BPC_LoadingScreen` (110) + `WBP_LoadingHorror`.

### WBP_LoadingHorror Widget

| Element | Type | Content |
|---------|------|---------|
| `Background` | Image | Blurred asylum corridor screenshot |
| `ProgressBar` | Progress Bar | 0-100% level load progress |
| `TipText` | Text Block | Rotating atmosphere/lore tips |
| `TitleText` | Text Block | Chapter name (e.g., "Ward A — Patient Wing") |
| `LoadingSpinner` | Image (animated) | Small rotating void symbol |

### Tip Rotation (8-10 second cycle)

Shows random tip from a `DT_LoadingTips` Data Table:

| Tip | Category |
|-----|----------|
| "Darkness is your ally. Enemies can't see what they can't hear." | Stealth |
| "Batteries are scarce. Use the flashlight sparingly." | Resource |
| "Listen. The asylum speaks to those who pay attention." | Atmosphere |
| "Not all doors need a key. Some need a different kind of opening." | Puzzle |
| "The void watches. It remembers. It waits." | Lore |
| "Running attracts attention. Sometimes walking is survival." | Stealth |
| "Check every drawer. The asylum hides its secrets well." | Exploration |
| "Your sanity is as important as your health." | Survival |
| "The patients aren't your enemy. They're victims too." | Lore |
| "Press ESC to pause. The horror will wait." | Meta |

---

## Main Menu Level Design

### L_MainMenu.umap

```
Level Layout (simple):
  ┌────────────────────────────────────────────┐
  │                                            │
  │   [3D Background: Asylum Hallway]          │
  │   - Static camera slowly pans left/right    │
  │   - Dim lighting, atmospheric fog           │
  │   - Distant flickering light bulb           │
  │   - Occasional distant sound (creak)        │
  │                                            │
  │        ┌─────────────────────┐             │
  │        │   PROJECT VOID      │             │
  │        │ ═══════════════     │             │
  │        │                     │             │
  │        │ [ NEW GAME      ]   │             │
  │        │ [ CONTINUE      ]   │             │
  │        │ [ LOAD GAME     ]   │             │
  │        │ [ SETTINGS      ]   │             │
  │        │ [ CREDITS       ]   │             │
  │        │ [ QUIT          ]   │             │
  │        │                     │             │
  │        │  v1.0 — UE5 Demo   │             │
  │        └─────────────────────┘             │
  │                                            │
  └────────────────────────────────────────────┘

Setup in UE5:
  1. Create new Level: L_MainMenu
  2. Add a BoxReflectionCapture + SkyLight (low intensity)
  3. Add a PostProcessVolume with horror color grading:
     - Saturation: 0.7
     - Contrast: 1.1
     - Color Grading: cool blue tint
  4. Place a CameraActor for the background
     - Animate via Matinee or Sequencer (slow pan)
  5. Add BP_RoomAudioZone with Lobby preset
  6. In Level Blueprint: OnBeginPlay → SS_UIManager.ShowMenu(MainMenu)
  7. In World Settings: GameMode Override = GM_HorrorGameMode
```

---

## Scene Transition Blueprint Pattern

Every chapter transition follows this pattern. Use this as a macro:

```
TransitionToChapter (ChapterTag: GameplayTag)
   │
   ├─ 1. PRE-TRANSITION
   │    ├─ GI_GameFramework.SetGamePhase(Loading)
   │    ├─ SS_UIManager.HideAllMenus()
   │    ├─ BPC_LoadingScreen.Show(WBP_LoadingHorror)
   │    └─ BPC_StateManager.ForcePushState(Loading)
   │
   ├─ 2. WORLD STATE CAPTURE
   │    ├─ BPC_PersistentWorldStateRecorder.SaveWorldState()
   │    └─ SS_SaveManager.CreateAutoSave("ChapterTransition")
   │
   ├─ 3. LEVEL LOAD
   │    ├─ GM_HorrorGameMode.HorrorLevelNames.Find(ChapterTag)
   │    └─ OpenLevel(LevelName)
   │
   ├─ 4. POST-LOAD (Level Blueprint OnBeginPlay)
   │    ├─ Set ChapterTag on GS_HorrorGameState
   │    ├─ BPC_NarrativeStateSystem.OnChapterStart(ChapterTag)
   │    ├─ BPC_AtmosphereStateController.LoadProfile(ChapterTag)
   │    ├─ BP_RoomAudioZone auto-activates on overlap
   │    ├─ BPC_PacingDirector.SetIntensityBand(ChapterTag)
   │    └─ Spawn player at level's PlayerStart actor
   │
   └─ 5. RESUME
        ├─ GI_GameFramework.SetGamePhase(InGame)
        ├─ BPC_LoadingScreen.Hide()
        └─ BPC_StateManager.RestorePreviousState()
```

---

## Blueprint Wiring Checklist

### L_SplashScreen Level
- [ ] Create empty level, add DirectionalLight + SkyLight
- [ ] Create WBP_SplashHorror widget (child of WBP_SplashScreen)
- [ ] In Level Blueprint: OnBeginPlay → AddToViewport(WBP_SplashHorror)
- [ ] Wire splash sequence: StudioLogo → EngineLogo → TitleCard → Warning → auto-advance
- [ ] On sequence complete: OpenLevel("L_MainMenu")
- [ ] Bind Skip: Any key press → jump to end of sequence

### L_MainMenu Level
- [ ] Create level with 3D background + CameraActor
- [ ] Create WBP_GameMainMenu widget (child of WBP_MainMenu)
- [ ] In Level Blueprint: OnBeginPlay → SS_UIManager.ShowMenu(MainMenu)
- [ ] Wire New Game → LoadingScreen → L_Asylum_Entry
- [ ] Wire Continue → SS_SaveManager.LoadLatest → LoadingScreen → target level
- [ ] Wire Settings → SS_UIManager.PushMenu(SettingsMenu)
- [ ] Wire Credits → L_Credits
- [ ] Wire Quit → Confirm dialog → GI_HorrorGame.QuitToDesktop

### Loading Screen
- [ ] Create WBP_LoadingHorror (child of BPC_LoadingScreen's widget class)
- [ ] Add progress bar, tip text, chapter title
- [ ] Create DT_LoadingTips Data Table with 10 tips
- [ ] Wire: OnShow → start tip rotation timer (every 8s, random tip)
- [ ] Wire: OnProgress → update progress bar
- [ ] Wire: OnHide → stop timer, remove from viewport

### Death Screen (overlay, not separate level)
- [ ] Create WBP_DeathScreen widget
- [ ] Show on death with: "You Died" + stats (chapter, deaths, time)
- [ ] Button: "Continue" → trigger respawn flow
- [ ] Button: "Return to Menu" → L_MainMenu

---

## Notes for Expansion

- Each chapter could have unique **loading screen backgrounds** (screenshots of key locations)
- Add **seamless streaming** for smaller areas — use `LoadStreamLevel` instead of `OpenLevel` for connected zones
- The void space could be **procedurally generated** — use `BPC_AdaptiveEnvironmentDirector` to generate rooms
- Consider adding a **chapter select** screen for debug/testing (bound to dev cheats)
- The tutorial sequence could have **difficulty detection** — if player dies once, tone down enemies
- Add a **"Return to Checkpoint"** option alongside "Continue" on the death screen

---

*Scene Flow for Project Void. See [GAMEINDEX.md](GAMEINDEX.md) for full game structure. See [44_SS_UIManager.md](../blueprints/06-ui/44_SS_UIManager.md) for menu stack management.*
