b2b6e1e7c7
- Created detailed documentation for systems 102-135 covering achievements, settings, polish, data assets, input management, and state management. - Added INDEX.md for easy navigation of developer reference materials. - Introduced architecture-overview.md to provide a high-level understanding of the framework's structure and communication methods. - Compiled implementation-patterns.md to outline common UE5 Blueprint patterns for consistent development practices.
187 lines
10 KiB
Markdown
187 lines
10 KiB
Markdown
# 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.*
|