# 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