admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

add blueprints

Browse Source
This commit is contained in:
Lefteris Notas
2026-05-19 13:22:27 +03:00
parent f71bc678b2
commit 411edea8ce
138 changed files with 23330 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

173
docs/blueprints/11-meta/102_BPC_ProgressStatTracker.md Normal file
View File

@@ -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

136
docs/blueprints/11-meta/103_SS_AchievementSystem.md Normal file
View File

@@ -0,0 +1,136 @@
# SS_AchievementSystem — Achievement System Subsystem
## Blueprint Spec — UE 5.5–5.7
---
### Parent Class
`UGameInstanceSubsystem`
### Dependencies
- **Requires:** [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Persist achievement data
- **Requires:** [`BPC_PlayerMetricsTracker`](../02-player/15_BPC_PlayerMetricsTracker.md) — Player stats source
- **Requires:** [`BPC_NarrativeStateSystem`](../07-narrative/38_BPC_NarrativeStateSystem.md) — Story progression
- **Required By:** [`WBP_NotificationToast`](../06-ui/WBP_NotificationToast.md) — UI notification
- **Required By:** [`BPC_PlatformServiceAbstraction`](../12-settings/BPC_PlatformServiceAbstraction.md) — Platform API submission
- **Engine/Plugin Requirements:** GameplayTags
### Purpose
Platform-agnostic achievement and trophy tracking system. Manages achievement definitions, progress tracking, unlock logic, and platform API submission. Supports hidden achievements, progress-based achievements, and cross-save achievement state persistence.
---
### Enums
**E_AchievementState**
| Value | Description |
|-------|-------------|
| Locked | Not yet discovered |
| InProgress | Progress saved but not complete |
| Unlocked | Achievement earned |
| Hidden | Not shown to player until unlocked |
**E_AchievementCategory**
| Value | Description |
|-------|-------------|
| Story | Story progression achievements |
| Exploration | Discovery and map completion |
| Combat | Enemy kill and combat achievements |
| Collectible | Item and lore collection |
| Challenge | Skill-based achievements |
| Difficulty | Difficulty-based achievements |
| Secret | Hidden achievements |
| Completionist | 100% completion |
---
### Structs
**S_AchievementState**
| Field | Type | Description |
|-------|------|-------------|
| AchievementTag | GameplayTag | Unique identifier |
| Title | FText | Display name |
| Description | FText | How to unlock |
| HiddenDescription | FText | Description shown after unlock |
| Category | E_AchievementCategory | Grouping |
| State | E_AchievementState | Current state |
| ProgressCurrent | Float | Current progress (0–1) |
| ProgressTarget | Float | Target value |
| bShowProgress | Bool | Show progress bar |
| Icon | Texture2D | Achievement image |
| Gamerscore | Int32 | Points value |
| bIsCrossSave | Bool | Persists across all saves |
---
### Variables
| Name | Type | Description |
|------|------|-------------|
| `AchievementRegistry` | Map (GameplayTag → S_AchievementState) | All achievement definitions and current state |
| `UnlockedAchievements` | Set of GameplayTag | Already unlocked achievement tags |
| `TotalGamerscore` | Int32 | Cumulative score |
| `bAchievementPopupEnabled` | Bool | Toast display toggle |
| `PendingAchievementQueue` | Array of S_AchievementState | Toasts waiting to show |
| `bShowingAchievement` | Bool | Currently displaying toast |
| `bOfflineMode` | Bool | Platform submission deferred |
---
### Functions
| Name | Inputs | Outputs | Description |
|------|--------|---------|-------------|
| `Initialize` | — | — | Load achievement data, register callbacks |
| `NotifyEvent` | EventTag: GameplayTag, Value: Float | — | Called by game systems; checks all relevant achievements |
| `UnlockAchievement` | AchievementTag: GameplayTag | — | Marks unlocked, submits to platform |
| `UpdateProgress` | AchievementTag: GameplayTag, Delta: Float | — | Increments progress tracker |
| `GetAchievementState` | AchievementTag: GameplayTag | S_AchievementState | Returns current state |
| `GetAllAchievements` | — | Array of S_AchievementState | For achievements menu |
| `GetAchievementsByCategory` | Category: E_AchievementCategory | Array of S_AchievementState | Filter by category |
| `GetUnlockedCount` | — | Int32 | Total unlocked |
| `GetTotalGamerscore` | — | Int32 | Cumulative score |
| `IsUnlocked` | AchievementTag: GameplayTag | Bool | Quick check |
| `SaveAchievementData` | — | — | Persist to save |
| `LoadAchievementData` | — | — | Read from save |
| `SubmitPendingToPlatform` | — | — | Flush pending on reconnect |
---
### Event Dispatchers
| Name | Parameters | Fired When |
|------|-----------|-----------|
| `OnAchievementUnlocked` | AchievementTag: GameplayTag, Gamerscore: Int32 | Achievement earned |
| `OnProgressUpdated` | AchievementTag: GameplayTag, NewProgress: Float | Progress changed |
---
### Communications With
| Target | Method | Why |
|--------|--------|-----|
| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Persistence |
| [`BPC_PlayerMetricsTracker`](../02-player/15_BPC_PlayerMetricsTracker.md) | Direct read | Stats for achievements |
| [`BPC_NarrativeStateSystem`](../07-narrative/38_BPC_NarrativeStateSystem.md) | Direct read | Story achievements |
| [`WBP_NotificationToast`](../06-ui/WBP_NotificationToast.md) | Create widget | Toast display |
| [`BPC_PlatformServiceAbstraction`](../12-settings/BPC_PlatformServiceAbstraction.md) | Direct call | Platform submission |
---
### Reuse Notes
- Achievements are data-driven from [`DA_AchievementData`](../14-data-assets/) assets
- Progress tracking enables percentage-based achievements
- Hidden achievements use separate description after unlock
- Toast queue prevents overlap during rapid unlocks
- Cross-save flag enables achievements that persist across save slots
- Gamerscore total is calculated automatically
- Renamed from `BPC_AchievementManager` to `SS_AchievementSystem` per Master naming convention.
---
*Specification based on Master Section 11.1, line 3116.*