add blueprints

2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
--- a/docs/blueprints/11-meta/102_BPC_ProgressStatTracker.md
+++ b/docs/blueprints/11-meta/102_BPC_ProgressStatTracker.md
@@ -0,0 +1,173 @@
+# 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