173 lines
7.2 KiB
Markdown
173 lines
7.2 KiB
Markdown
# 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 |