# 75 — BPC_StatsTracker

## Blueprint Spec — UE 5.5–5.7

---

### Parent Class
`ActorComponent`

### Dependencies
- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Persist stat data
- [`BPC_PlayerMetricsTracker`](../02-player/14_BPC_PlayerMetricsTracker.md) — Player metrics source
- [`BPC_AchievementManager`](../11-polish/74_BPC_AchievementManager.md) — Feed data for achievements
- [`WBP_StatsDisplay`](../06-ui/45_WBP_StatsDisplay.md) — UI display (Phase 5)
- [`BPC_InventoryComponent`](../04-inventory/24_BPC_InventoryComponent.md) — Item usage stats
- [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) — Story stats

### Purpose
Comprehensive session and lifetime statistics tracker. Records player actions, progression metrics, gameplay statistics, and efficiency data. Provides aggregated stats for achievement validation, end-game summary screens, and player analytics. Supports session-only stats and cumulative lifetime tracking.

### Enums

**EStatsCategory**

| Value | Description |
|-------|-------------|
| Combat | Combat-related stats |
| Exploration | Movement and discovery |
| Survival | Health, stamina, resource management |
| Inventory | Item collection and crafting |
| Story | Narrative progression |
| Efficiency | Speed and resource efficiency |
| Misc | Catch-all category |

**EStatsScope**

| Value | Description |
|-------|-------------|
| Session | Reset on each play session |
| Lifetime | Persistent across all saves |
| Chapter | Tracked per chapter |

### Structs

**FStatsEntry**

| Field | Type | Description |
|-------|------|-------------|
| StatID | FName | Unique identifier |
| Category | EStatsCategory | Grouping |
| DisplayName | FText | User-facing name |
| CurrentValue | Float | Current tracked value |
| BestValue | Float | Personal best |
| bTrackBest | Bool | Whether to track best |
| Scope | EStatsScope | Persistence scope |

### Variables

| Name | Type | Description |
|------|------|-------------|
| `StatsRegistry` | TMap\<FName, FStatsEntry\> | All tracked stats |
| `SessionStats` | TMap\<FName, Float\> | Session-only values |
| `LifetimeStats` | TMap\<FName, Float\> | Persistent values |
| `ChapterStats` | TMap\<FName, TMap\<FName, Float\>\> | Per-chapter tracking |
| `CurrentChapter` | FName | Active chapter ID |
| `bTrackingEnabled` | Bool | Master toggle |

### Functions

| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Initialize` | — | — | Load lifetime stats, register callbacks |
| `RegisterStat` | Entry: FStatsEntry | — | Add stat to registry |
| `IncrementStat` | StatID: FName, Delta: Float | — | Add value |
| `SetStat` | StatID: FName, Value: Float | — | Override value |
| `GetStat` | StatID: FName | Float | Current value |
| `GetBestStat` | StatID: FName | Float | Personal best |
| `ResetSessionStats` | — | — | Clear session data |
| `SaveStats` | — | — | Persist lifetime stats |
| `LoadStats` | — | — | Restore lifetime stats |
| `GetStatsByCategory` | Category: EStatsCategory | TArray\<FStatsEntry\> | Filter |

### Predefined Stat Definitions

| StatID | Category | Scope | Description |
|--------|----------|-------|-------------|
| TotalKills | Combat | Lifetime | Total enemy kills |
| HeadshotKills | Combat | Lifetime | Headshot kills |
| MeleeKills | Combat | Lifetime | Melee kills |
| StealthKills | Combat | Lifetime | Undetected kills |
| TotalDamageDealt | Combat | Lifetime | Damage inflicted |
| TotalDamageTaken | Survival | Lifetime | Damage received |
| TimesDeath | Survival | Lifetime | Player deaths |
| TimesHealed | Survival | Lifetime | Healing items used |
| DistanceWalked | Exploration | Lifetime | Total walked distance |
| DistanceRan | Exploration | Lifetime | Total sprint distance |
| DistanceCrouched | Exploration | Lifetime | Total crouch distance |
| RoomsExplored | Exploration | Lifetime | Unique rooms entered |
| ItemsCollected | Inventory | Lifetime | Total items picked up |
| ItemsCrafted | Inventory | Lifetime | Items crafted |
| KeysUsed | Inventory | Lifetime | Keys consumed |
| NotesFound | Story | Lifetime | Lore documents |
| DialoguesCompleted | Story | Lifetime | Dialogue sequences |
| ChaptersCompleted | Story | Lifetime | Chapters finished |
| TimePlayed | Misc | Lifetime | Total play time |
| SessionTime | Misc | Session | Current session time |
| TimesSaved | Misc | Lifetime | Manual saves |
| AttemptsCurrentChapter | Misc | Chapter | Retries this chapter |
| Accuracy | Combat | Session | Hit percentage |
| FastestCompletion | Efficiency | Lifetime | Speedrun records |

### Blueprint Flow

```
[Initialize]
  └─► LoadStats() from SS_SaveManager
  └─► Register all predefined stats
  └─► Start session timer
  └─► Bind event listeners:
         BPC_PlayerMetricsTracker.OnEnemyKilled -> IncrementStat(TotalKills)
         BPC_PlayerMetricsTracker.OnDamageDealt -> IncrementStat(TotalDamageDealt)
         BPC_PlayerMetricsTracker.OnDamageTaken -> IncrementStat(TotalDamageTaken)
         BPC_PlayerMetricsTracker.OnPlayerDeath -> IncrementStat(TimesDeath)
         BPC_PlayerMetricsTracker.OnHealingApplied -> IncrementStat(TimesHealed)
         BPC_InventoryComponent.OnItemAdded -> IncrementStat(ItemsCollected)
         BPC_NarrativeState.OnNarrativePhaseChanged -> ChaptersCompleted

[IncrementStat Flow]
  └─► If not bTrackingEnabled: return
  └─► If Scope == Session: Update SessionStats
  └─► Else if Scope == Lifetime: Update LifetimeStats
  └─► Else if Scope == Chapter: Update ChapterStats[CurrentChapter]
  └─► If bTrackBest and new value > BestValue: Update BestValue
  └─► Broadcast OnStatUpdated(StatID, NewValue)

[SaveStats Flow]
  └─► Aggregate all lifetime stats into save data
  └─► Call SS_SaveManager.WriteStatData(StatsData)
  └─► Called on: Level transition, manual save, chapter completion

[EndSession Flow]
  └─► Called on game quit
  └─► Save lifetime stats
  └─► Log session summary
  └─► Reset session stats
```

### Event Dispatchers

| Name | Payload | Description |
|------|---------|-------------|
| `OnStatUpdated` | StatID: FName, NewValue: Float | Any stat changes |
| `OnSessionStatsReset` | — | New session begins |

### Communications With

| Target | Method | Why |
|--------|--------|-----|
| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Persistence |
| [`BPC_PlayerMetricsTracker`](../02-player/14_BPC_PlayerMetricsTracker.md) | Event | Player action stats |
| [`BPC_AchievementManager`](../11-polish/74_BPC_AchievementManager.md) | Direct call | Feed achievement data |
| [`BPC_InventoryComponent`](../04-inventory/24_BPC_InventoryComponent.md) | Event | Collection stats |
| [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) | Event | Progress stats |
| [`WBP_StatsDisplay`](../06-ui/45_WBP_StatsDisplay.md) | Event | UI updates |

### Reuse Notes
- Separates session, lifetime, and chapter scoping
- Best-value tracking enables personal records
- Categories enable filtered UI display
- All stats are data-driven; new stats added via RegisterStat
- Session stats auto-reset on game start
- Chapter stats feed into end-of-chapter summaries
- Lifetime stats persist across all save slots