15d6e88780
- Added BPC_PlatformServiceAbstraction to centralize platform detection and SDK routing for achievements, cloud saves, and overlays. - Updated dependencies across various systems to utilize the new platform service for consistent platform handling. - Deprecated old platform enums in favor of a unified EPlatformFamily enum. - Enhanced documentation for affected systems to reflect changes in platform handling and dependencies.
136 lines
5.6 KiB
Markdown
136 lines
5.6 KiB
Markdown
# 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.* |