diff --git a/Save%2FLoad%2C-Persistence-%26-Death-Loop-Systems.md b/Save%2FLoad%2C-Persistence-%26-Death-Loop-Systems.md new file mode 100644 index 0000000..e525a39 --- /dev/null +++ b/Save%2FLoad%2C-Persistence-%26-Death-Loop-Systems.md @@ -0,0 +1,186 @@ +# 05 — Save/Load, Persistence & Death Loop Systems (Systems 35-43) + +**Category Purpose:** These 9 systems handle everything related to game state persistence — saving and loading player progress, checkpoint management, the death/respawn loop, the alternate death space (void/purgatory mechanic), persistent corpses, world state recording, run history tracking, and the `I_Persistable` interface contract that all saveable actors implement. + +--- + +## System Index + +| # | System | Asset Type | Role | +|---|--------|-----------|------| +| 35 | `SS_SaveManager` | Subsystem | Save/load subsystem; slot management, serializer, manifest | +| 36 | `I_Persistable` | Interface | Persistence contract for any actor that saves state | +| 37 | `BP_Checkpoint` | Actor | Checkpoint actor; respawn point, activation, save-on-touch | +| 38 | `BPC_AltDeathSpaceSystem` | Component | Alternate death/void space; enter, explore, find exit | +| 39 | `BPC_DeathHandlingSystem` | Component | Death orchestrator; outcome determination, animation, respawn | +| 40 | `BPC_PersistentCorpseSystem` | Component | Corpse persistence across death/respawn/level transitions | +| 41 | `BPC_PersistentWorldStateRecorder` | Component | Records world state changes (doors, items, enemies) for save | +| 42 | `BPC_PlayerRespawnSystem` | Component | Respawn logic; checkpoint resolution, state restoration | +| 43 | `BPC_RunHistoryTracker` | Component | Run/session history; death count, time, checkpoint progression | + +--- + +## Category Data Flow — The Death Loop + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ DEATH & PERSISTENCE │ +│ │ +│ BPC_HealthSystem.OnDeath │ +│ ↓ │ +│ BPC_DeathHandlingSystem (death orchestrator) │ +│ │ Determines outcome: Alt Death Space? Normal Respawn? │ +│ ├─► Alt Death Space: │ +│ │ BPC_AltDeathSpaceSystem.Enter() │ +│ │ Player explores void/purgatory │ +│ │ Find exit → RestorePreviousState() │ +│ │ │ +│ └─► Normal Respawn: │ +│ GM_CoreGameMode.HandlePlayerDead() │ +│ SS_SaveManager.LoadCheckpoint() │ +│ BPC_PlayerRespawnSystem.Respawn() │ +│ │ +│ SS_SaveManager (persistence subsystem) │ +│ │ Manages save slots, serialization, manifest │ +│ ├─► OnSave: iterates all I_Persistable actors │ +│ ├─► OnLoad: restores actor states from save file │ +│ │ │ +│ │ Coordinates with: │ +│ ├─► BPC_PersistentWorldStateRecorder (world changes) │ +│ ├─► BPC_PersistentCorpseSystem (corpse data) │ +│ └─► BP_Checkpoint (save-on-touch activation) │ +│ │ +│ BPC_RunHistoryTracker (session stats) │ +│ │ Tracks: death count, play time, checkpoint progression │ +│ └─► Persists across sessions for meta-progression │ +└──────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 35 — SS_SaveManager: Save/Load Subsystem + +**What It Does:** The central save/load authority as a GameInstanceSubsystem. Manages save slots (create, load, delete, list), handles serialization of all `I_Persistable` actors, maintains a save slot manifest, and coordinates with platform save services. + +**How It Works Internally:** + +**Save Protocol:** +1. Save triggered (manual, auto-save, checkpoint) +2. Iterates all actors implementing `I_Persistable` in the world +3. Each actor returns its state via `OnSave()` as a GameplayTagContainer +4. Serializes all actor states + global data (chapter, play time, objectives) to save file +5. Updates slot manifest with timestamp, screenshot, play time + +**Load Protocol:** +1. Load slot selected +2. Deserializes save file +3. Loads correct level/chapter +4. Iterates `I_Persistable` actors, calls `OnLoad(SaveData)` on each +5. Restores global state (chapter, objectives, inventory) +6. Player placed at appropriate spawn point + +**Slot Management:** +- Multiple save slots with metadata (timestamp, play time, chapter name, thumbnail) +- Auto-save slot separate from manual slots +- Slot manifest tracks all available saves + +--- + +## 36 — I_Persistable: Persistence Interface + +**What It Does:** The contract that any actor must implement to be saveable. The save system scans the world for `I_Persistable` implementors and calls these functions. + +**Key Functions:** +- `OnSave()` → returns actor state as GameplayTagContainer for serialization +- `OnLoad(SaveData)` → restores actor state from saved data +- `GetSaveTag()` → returns unique GameplayTag identifying this actor for lookup +- `NeedsSave()` → whether this actor has unsaved changes + +**Implementation:** Doors (save locked/open state), chests (looted/not), enemies (alive/dead/position), items (collected/not), narrative triggers (fired/not), checkpoints (active/not). + +--- + +## 37 — BP_Checkpoint: Checkpoint Actor + +**What It Does:** A world-placed actor that serves as a respawn point. On player touch or interaction, becomes the active checkpoint. Triggers auto-save. Overrides previous checkpoint. + +**Features:** +- Activates on overlap or interaction +- Stores checkpoint transform (player respawn location/rotation) +- Triggers `SS_SaveManager.AutoSave()` on activation +- Visual states: inactive (dim), active (glowing), previous (faded) +- One checkpoint active at a time +- Save-on-touch: automatic save reduces lost progress + +--- + +## 38 — BPC_AltDeathSpaceSystem: Alternate Death Space + +**What It Does:** Implements the "void space" or "purgatory" mechanic — when the player dies in specific circumstances, instead of a standard respawn, they enter an alternate death dimension. They must explore this space, find an exit, and return to the main world. + +**State Machine:** +1. `Enter()` — player dies, teleports to death space level +2. Player explores void environment (puzzle, narrative, combat) +3. `FindExit()` — player discovers exit point +4. `Exit()` — teleports back to main world at respawn point +5. Fires `RestorePreviousState()` — pops back from force stack + +**Features:** +- Separate level or sub-level for death space +- Unique atmosphere, enemies, and narrative content +- Exit conditions configurable (time, puzzle solve, item find) +- Multiple death space variants possible +- Coordinates with `BPC_DeathHandlingSystem` for entry conditions + +--- + +## 39 — BPC_DeathHandlingSystem: Death Orchestrator + +**What It Does:** Listens for `BPC_HealthSystem.OnDeath` and determines what happens next. The central death logic router — decides between alt death space, checkpoint respawn, permadeath, or game over. + +**Flow:** +1. Binds to `OnDeath` dispatcher +2. Determines death context: enemy killed? environmental? scripted? +3. Checks `BPC_DeathCauseTracker` for specific death cause +4. Evaluates conditions: + - Should alt death space trigger? (configurable chance / specific enemies) + - Is this permadeath mode? → wipe save + - Normal death? → checkpoint respawn +5. Routes to appropriate system: `BPC_AltDeathSpaceSystem.Enter()` or `GM_CoreGameMode.HandlePlayerDead()` +6. Plays death animation, screen effects +7. Logs death to `BPC_RunHistoryTracker` + +--- + +## 40 — BPC_PersistentCorpseSystem: Corpse Persistence + +**What It Does:** When the player dies, their previous body becomes a persistent corpse in the world. On respawn, the old body remains as a lootable container with the player's previous inventory. Corpses persist across deaths and level transitions. + +**Features:** +- Spawns corpse actor at death location with player's appearance +- Contains `BPC_ContainerInventory` with player's previous items +- Corpse persists across respawns (doesn't disappear) +- Configurable corpse limit (oldest despawns when max reached) +- Companions can loot player corpse (co-op) + +--- + +## 41-43: Supporting Systems + +- **41 BPC_PersistentWorldStateRecorder:** Records every world state change (door opened, item collected, enemy killed) to a change log for save/load. On load, replays changes to restore exact world state. +- **42 BPC_PlayerRespawnSystem:** Loads checkpoint data, places player at checkpoint transform, restores health/stamina/inventory from save state, applies brief invincibility. +- **43 BPC_RunHistoryTracker:** Tracks per-session stats: death count, play time, checkpoints reached, enemies killed, items collected. Persists for meta-progression (achievements, difficulty scaling). + +--- + +## Common Implementation Patterns in This Category + +1. **Force Stack Pattern:** Death and alt death space push state onto a stack; `RestorePreviousState()` pops back. Enables nested state changes (death → void → return). +2. **Interface-Based Persistence:** Save system doesn't know about doors or enemies — it only calls `I_Persistable.OnSave()` / `OnLoad()`. Any new saveable type just implements the interface. +3. **Save Tag Uniqueness:** Each saveable actor has a unique GameplayTag for identity. The save file maps tag → serialized state. +4. **Checkpoint Cascade:** Checkpoints are linear — activating a new one overrides the previous. Auto-save on activation prevents progress loss. +5. **Corpse as Container:** Corpses reuse `BPC_ContainerInventory` — no special corpse inventory code needed. + +--- + +*Developer Reference v1.0 — 05 Save/Load Systems. Companion to docs/blueprints/05-saveload/ specs.*