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/103_SS_AchievementSystem.md
+++ b/docs/blueprints/11-meta/103_SS_AchievementSystem.md
@@ -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.*