# 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`](../01-core/150_BPC_PlatformServiceAbstraction.md) — Platform API routing (Steam/PSN/Xbox/Nintendo)
- **Engine/Plugin Requirements:** GameplayTags, Platform SDK plugins (Steamworks, PSN, Xbox GDK, Nintendo SDK — all optional)

### 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`](../01-core/150_BPC_PlatformServiceAbstraction.md) | Direct call | Platform SDK routing (Steam/PSN/Xbox/Nintendo) |

---

### 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.*