UE5-Modular-Game-Framework/docs/blueprints/11-meta/102_BPC_ProgressStatTracker.md

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