75 — BPC_StatsTracker

Blueprint Spec — UE 5.5–5.7

Parent Class

ActorComponent

Dependencies

SS_SaveManager — Persist stat data
BPC_PlayerMetricsTracker — Player metrics source
BPC_AchievementManager — Feed data for achievements
WBP_StatsDisplay — UI display (Phase 5)
BPC_InventoryComponent — Item usage stats
BPC_NarrativeState — 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`	Direct call	Persistence
`BPC_PlayerMetricsTracker`	Event	Player action stats
`BPC_AchievementManager`	Direct call	Feed achievement data
`BPC_InventoryComponent`	Event	Collection stats
`BPC_NarrativeState`	Event	Progress stats
`WBP_StatsDisplay`	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

7.2 KiB Raw Blame History Unescape Escape