add blueprints

docs/blueprints/05-saveload/43_BPC_RunHistoryTracker.md

@@ -0,0 +1,90 @@
+# BPC_RunHistoryTracker — Actor Component (Run History)
+
+**File:** [`Content/Framework/Save/BPC_RunHistoryTracker`](Content/Framework/Save/BPC_RunHistoryTracker.uasset)
+
+**Purpose:** Records session-level death and run data for the run summary screen (death recap, stats, journal entries tied to the run). Not saved to the main save file but stored per-session for display at game over.
+
+**Depends On:** [`BPC_DeathHandlingSystem`](BPC_DeathHandlingSystem.md)
+**Used By:** [`BPC_DeathHandlingSystem`](BPC_DeathHandlingSystem.md) (orchestrator), UI (Run Summary screen)
+
+---
+
+## Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `RunHistory` | Array of `S_DeathContext` | Every death this run, in order |
+| `RunStartTime` | FDateTime | When the current run started |
+| `RunEndTime` | FDateTime | When the run ended (game over or quit) |
+| `TotalDeathsThisRun` | Integer | Convenience counter |
+| `bIsNewRun` | Bool | True until the first death occurs |
+
+---
+
+## Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `RecordDeath` | Context: S_DeathContext | — | Appends death to run history |
+| `GetRunHistory` | — | Array of S_DeathContext | Returns full death list |
+| `GetRunDuration` | — | FTimespan | RunStartTime to now |
+| `GetDeathCountThisRun` | — | Integer | Returns TotalDeathsThisRun |
+| `StartNewRun` | — | — | Clears history, sets RunStartTime to now |
+| `EndRun` | — | — | Sets RunEndTime to now |
+| `GetRunSummary` | — | FText | Formatted summary text for run recap UI |
+
+---
+
+## Event Dispatchers
+
+| Name | Parameters | Fired When |
+|------|-----------|------------|
+| `OnDeathRecorded` | DeathIndex: Integer, Context: S_DeathContext | A death was added to history |
+| `OnRunStarted` | StartTime: FDateTime | StartNewRun was called |
+| `OnRunEnded` | Duration: FTimespan, DeathCount: Integer | EndRun was called |
+
+---
+
+## Blueprint Flow
+
+```
+[RecordDeath: Context]
+  └─► Append Context to RunHistory array
+  └─► TotalDeathsThisRun = RunHistory.Length
+  └─► bIsNewRun = false
+  └─► Broadcast OnDeathRecorded(TotalDeathsThisRun - 1, Context)
+
+[StartNewRun]
+  └─► Clear RunHistory array
+  └─► Set RunStartTime = CurrentDateTime
+  └─► Set TotalDeathsThisRun = 0
+  └─► Set bIsNewRun = true
+  └─► Broadcast OnRunStarted(RunStartTime)
+
+[EndRun]
+  └─► Set RunEndTime = CurrentDateTime
+  └─► Broadcast OnRunEnded(GetRunDuration(), TotalDeathsThisRun)
+
+[GetRunSummary]
+  └─► Format: "Run Duration: {duration}\nDeaths: {count}\nDeath 1: {context.KillerTag} at {context.DeathLocation}"
+  └─► Return formatted FText
+```
+
+---
+
+## Communications With
+
+| Target System | Method | Why |
+|---------------|--------|-----|
+| [`BPC_DeathHandlingSystem`](BPC_DeathHandlingSystem.md) | Direct call | Orchestrator records deaths and ends runs |
+| [`GM_CoreGameMode`](../01-core/05_GM_CoreGameMode.md) | Direct call | Start new run on game start |
+| UI (WBP_RunSummary) | Dispatcher / Function | Display run summary on game over |
+| [`BPC_EndingAccumulator`](../07-narrative/BPC_EndingAccumulator.md) | Direct call | Death count feeds into ending evaluation |
+
+---
+
+## Reuse Notes
+- Run history is session-only and NOT serialised — it resets on game restart
+- The RunHistory array grows unbounded within a session (typically < 20 entries)
+- RunSummary text formatting can be overridden per project for localization
+- Split from original bundled `31_BPC_DeathHandlingSystem.md` per Clean Slate refactoring plan