UE5-Modular-Game-Framework/docs/blueprints/02-player/15_BPC_PlayerMetricsTracker.md

15 — Player Metrics Tracker (BPC_PlayerMetricsTracker)

Purpose

Records and exposes player behaviour telemetry throughout a play session. Metrics feed into the adaptive difficulty system, achievement tracking, end-game stats screen, and narrative pacing adjustments. This is a pure data-gathering component — it never blocks or modifies gameplay directly.

Dependencies

• Requires: GI_GameFramework (session start/end events), DA_GameDifficulty (adaptive thresholds)
• Required By: BPC_AdaptiveDifficulty (consumes metrics), WBP_StatsScreen (end-game display), GM_CoreGameMode (death/checkpoint metrics)
• Engine/Plugin Requirements: FTimerHandle for play time tracking

Class Info

Property	Value
Parent Class	ActorComponent
Class Type	Blueprint Component
Asset Path	Content/Framework/Player/BPC_PlayerMetricsTracker
Implements Interfaces	I_Persistable (save/load metrics)

---

1. Enums

E_MetricEventType

Value	Description
Death = 0	Player died
HideStarted = 1	Player entered a hide spot
HideEnded = 2	Player exited a hide spot
ItemCollected = 3	Player picked up an item
EnemyEncountered = 4	Player entered an enemy detection range
EnemyEvaded = 5	Player escaped enemy detection
StressPeakReached = 6	Stress tier exceeded Distressed
AreaExplored = 7	Player entered a new area/chapter
NarrativeEvent = 8	Story beat triggered
CombatEvent = 9	Player used a weapon or was attacked

---

2. Structs

S_BehaviourEvent

Field	Type	Description
Timestamp	Float	Game time in seconds when event occurred
EventType	E_MetricEventType	What happened
ContextTag	GameplayTag	Tagged context for filtering
FloatValue	Float	Numeric payload (e.g. distance, intensity)
StringValue	String	Text payload (e.g. location name, enemy ID)
Location	Vector	World location where event occurred

S_MetricsSnapshot

Field	Type	Description
TotalPlayTime	Float	Total seconds played
TimesDied	Integer	Total deaths this session
TimesHid	Integer	Total hide events
TotalDistanceWalked	Float	Cumulative walking distance (cm)
TotalDistanceSprinted	Float	Cumulative sprinting distance (cm)
ItemsCollected	Integer	Total items picked up
UniqueItemsCollected	Set<FName>	Names of unique items collected
EnemiesEncountered	Integer	Total unique enemy encounters
EnemiesEvaded	Integer	Total successful evasions
PeakStressTier	Float	Highest stress tier reached (as float)
StressPeakCount	Integer	Times stress exceeded Distressed threshold
NarrativeBeatsCompleted	Integer	Story triggers activated
AreasExplored	Set<FName>	Unique areas/chapters visited
CombatEvents	Integer	Total combat interactions

S_TimeSegment

Field	Type	Description
SegmentLabel	String	Label for this time segment
StartTime	Float	Game time at segment start
EndTime	Float	Game time at segment end
StressAverage	Float	Average stress during segment
MetricsDelta	S_MetricsSnapshot	Metrics accumulated in this segment

---

3. Variables

Configuration (Instance Editable, Expose On Spawn)

Variable	Type	Default	Category	Description
bTrackDetailedEvents	Boolean	true	Metrics Config	If true, store full S_BehaviourEvent history
MaxEventHistory	Integer	5000	Metrics Config	Cap on stored events to prevent memory bloat
bAutoSaveMetrics	Boolean	true	Metrics Config	Auto-save metrics via I_Persistable on quit
SnapshotInterval	Float	60.0	Metrics Config	Seconds between automatic snapshot writes

Computed / Runtime (Public, Blueprint Read Only)

Variable	Type	Default	Category	Description
CurrentSnapshot	S_MetricsSnapshot	-	Runtime Metrics	Live accumulated metrics this session
bIsTrackingSession	Boolean	false	Runtime Metrics	Whether currently in a tracked session
TimeSegmentHistory	Array<S_TimeSegment>	[]	Runtime Metrics	Historical segments for analysis
CurrentSegment	S_TimeSegment	-	Runtime Metrics	Active time segment

Internal (Private / Protected, No Expose)

Variable	Type	Default	Category	Description
SessionStartTime	Float	0.0	Timing	Game time when session started
CachedEventHistory	Array<S_BehaviourEvent>	[]	History	Full event history (if tracking enabled)
LastPosition	Vector	(0,0,0)	Tracking	Previous frame position for distance calc
SnapshotTimerHandle	FTimerHandle	-	Timing	Timer for automatic snapshots

Replicated (if multiplayer)

Variable	Type	Condition	Description
CurrentSnapshot	S_MetricsSnapshot	Replicated	Synced session metrics

---

4. Functions

Public Functions

StartSession → void

• Description: Begins a new metrics tracking session. Resets snapshot.
• Parameters:

  Param	Type	Description
  SegmentLabel	String	Label for initial segment (e.g. "Chapter 1")

• Blueprint Authority: Any
• Flow:
  1. Set SessionStartTime = Current Game Time
  2. Reset CurrentSnapshot to zero values
  3. Initialize CurrentSegment with label and start time
  4. Set bIsTrackingSession = true
  5. Start snapshot timer
  6. Fire OnSessionStarted

EndSession → S_MetricsSnapshot

• Description: Ends the tracking session and returns final snapshot.
• Parameters: None
• Flow:
  1. Finalize CurrentSegment end time
  2. Finalize CurrentSnapshot.PlayTime
  3. Add CurrentSegment to TimeSegmentHistory
  4. Set bIsTrackingSession = false
  5. Clear snapshot timer
  6. Fire OnSessionEnded
  7. Return CurrentSnapshot

RecordEvent → void

• Description: Records a single behaviour event into history and updates snapshot.
• Parameters:

  Param	Type	Description
  EventType	E_MetricEventType	Type of event
  ContextTag	GameplayTag	Filtering tag
  FloatValue	Float	Numeric payload
  StringValue	String	Text payload

• Flow:
  1. If not bIsTrackingSession: return
  2. Create S_BehaviourEvent with current timestamp
  3. If bTrackDetailedEvents and event count < MaxEventHistory:
     • Add event to CachedEventHistory
  4. Update CurrentSnapshot based on EventType:
     • Death: TimesDied++
     • HideStarted: TimesHid++
     • ItemCollected: ItemsCollected++, add name to UniqueItemsCollected
     • EnemyEncountered: EnemiesEncountered++
     • EnemyEvaded: EnemiesEvaded++
     • StressPeakReached: StressPeakCount++, update PeakStressTier if higher
     • NarrativeEvent: NarrativeBeatsCompleted++
     • AreaExplored: add to AreasExplored
     • CombatEvent: CombatEvents++
  5. Fire OnEventRecorded

RecordDistanceTraveled → void

• Description: Called by movement system or tick to log distance.
• Parameters:

  Param	Type	Description
  DistanceDelta	Float	Distance moved this frame
  bWasSprinting	Boolean	Whether player was sprinting

• Flow:
  1. If bWasSprinting: CurrentSnapshot.TotalDistanceSprinted += Delta
  2. Else: CurrentSnapshot.TotalDistanceWalked += Delta

GetMetricsSnapshot → S_MetricsSnapshot

• Description: Returns a copy of the current live snapshot.
• Parameters: None
• Flow: Return CurrentSnapshot

GetEventHistory → Array<S_BehaviourEvent>

• Description: Returns recorded event history.
• Parameters:

  Param	Type	Description
  bFiltered	Boolean	If true, apply filter
  FilterType	E_MetricEventType	Only return events of this type

• Flow:
  1. If bFiltered: return filtered CachedEventHistory by FilterType
  2. Else: return CachedEventHistory

GetPlayTimeFormatted → String

• Description: Returns total play time as formatted string (HH:MM:SS).
• Parameters: None
• Flow: Format SecondsToTimeString(SessionDuration)

Protected / Private Functions

OnTickDistance (Tick) → void

• Description: Each tick, compute distance from LastPosition. Only active when tracking.
• Flow:
  1. If not bIsTrackingSession: return
  2. Get current actor location
  3. Delta = Distance(LastPosition, CurrentLocation)
  4. If Delta < 10.0: skip (noise threshold)
  5. Check movement mode from BPC_MovementStateSystem
  6. Call RecordDistanceTraveled(Delta, bWasSprinting)
  7. Update LastPosition = CurrentLocation

CreateSnapshot → void

• Description: Timer callback to create periodic snapshots.
• Flow:
  1. Copy CurrentSnapshot as snapshot
  2. Finalize CurrentSegment end time
  3. Store snapshot delta in CurrentSegment.MetricsDelta
  4. Add CurrentSegment to TimeSegmentHistory
  5. Start new CurrentSegment

---

5. Event Dispatchers

Dispatcher	Parameters	Bind Access	Description
OnSessionStarted	String SegmentLabel	Public	Fired when a tracking session begins
OnSessionEnded	S_MetricsSnapshot FinalSnapshot	Public	Fired when a tracking session ends
OnEventRecorded	S_BehaviourEvent Event	Public	Fired each time an event is recorded
OnMetricsThresholdReached	E_MetricEventType EventType, int CurrentValue, int Threshold	Public	Fired when a metric crosses a threshold
OnSnapshotCreated	S_TimeSegment Segment	Public	Fired when a periodic snapshot is written

---

6. Overridden Events / Custom Events

Event: BeginPlay

• Description: Cache owner reference, start session if game has started.
• Flow:
  1. Get owning pawn
  2. Bind to GI_GameFramework.OnGamePhaseChanged
  3. If game phase is Playing: StartSession("Initial")

Custom Event: OnGamePhaseChangedHandler

• Description: Auto-start/stop session based on game phase.
• Flow:
  1. If NewPhase == Playing: StartSession("Resume")
  2. If NewPhase == Menu / Transition / Ended: EndSession()

---

7. Blueprint Graph Logic Flow

flowchart TD
    A[RecordEvent called] --> B{Is session active?}
    B -->|No| C[Return]
    B -->|Yes| D[Build S_BehaviourEvent]
    D --> E{Has history space?}
    E -->|Yes| F[Append to CachedEventHistory]
    E -->|No| G[Skip history store]
    G --> H[Update CurrentSnapshot counters]
    F --> H
    H --> I{Threshold crossed?}
    I -->|Yes| J[Fire OnMetricsThresholdReached]
    I -->|No| K[Fire OnEventRecorded]
    J --> K
    
    L[Tick: RecordDistanceTraveled] --> M[Get current location]
    M --> N[Distance from LastPosition]
    N --> O{Delta > 10 cm?}
    O -->|No| P[Skip]
    O -->|Yes| Q[Update snapshot distance]
    Q --> R[Set LastPosition]
    
    S[SnapshotTimer fires] --> T[Copy CurrentSnapshot]
    T --> U[Write segment to history]
    U --> V[Fire OnSnapshotCreated]

---

8. Communication Matrix

Who Talks	How	What Is Sent
BPC_PlayerMetricsTracker	Direct call (other)	GetMetricsSnapshot -> BPC_AdaptiveDifficulty
BPC_PlayerMetricsTracker	Dispatcher	OnEventRecorded -> BPC_AdaptiveDifficulty (real-time feed)
BPC_PlayerMetricsTracker	Dispatcher	OnSessionEnded -> WBP_StatsScreen (end-game display)
BPC_PlayerMetricsTracker	Dispatcher	OnMetricsThresholdReached -> GM_CoreGameMode (achievements)
BPC_HealthSystem	Direct	Calls RecordEvent(Death) on player death
BPC_HidingSystem	Direct	Calls RecordEvent(HideStarted/HideEnded)
BPC_StressSystem	Direct	Calls RecordEvent(StressPeakReached)
GI_GameFramework	Dispatcher	OnGamePhaseChanged -> BPC_PlayerMetricsTracker (start/stop)
BPC_NarrativeManager	Direct	Calls RecordEvent(NarrativeEvent) on story beat
BPC_WeaponSystem	Direct	Calls RecordEvent(CombatEvent) on attack
BPC_InventoryManager	Direct	Calls RecordEvent(ItemCollected) on pickup

---

9. Validation / Testing Checklist

• StartSession resets all counters to zero
• Distance tracking correctly accumulates walking vs sprinting
• Events are capped at MaxEventHistory and do not overflow
• Snapshot timer creates periodic snapshots at correct interval
• EndSession returns accurate final snapshot
• Filtered event history returns only matching event types
• Threshold dispatchers fire at correct metric values
• I_Persistable save/load preserves snapshot across sessions
• Edge case: Rapid events within one frame all recorded
• Edge case: Session ends with zero events — snapshot is valid zero-state
• Edge case: Distance tracking ignores teleportation (delta > 5000 cm)
• Formatted play time displays correctly for all durations

---

10. Reuse Notes

• The metrics snapshot is designed to be consumed by BPC_AdaptiveDifficulty for dynamic difficulty adjustment.
• Event history can be serialised to disk via I_Persistable for cross-session analytics.
• The same BPC_PlayerMetricsTracker can be attached to any character blueprint — not just the player.
• Threshold values are not defined here; they live in DA_GameDifficulty or DA_AdaptiveSettings.
• For debugging, call GetEventHistory(false) to dump all events to log.

---

Blueprint Spec: Player Metrics Tracker. Conforms to TEMPLATE.md v1.0 — part of the UE5 Modular Game Framework.