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/13-polish/106_BPC_AnalyticsTracker.md
+++ b/docs/blueprints/13-polish/106_BPC_AnalyticsTracker.md
@@ -0,0 +1,187 @@
+# 82 — BPC_AnalyticsTracker
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Queue flush on save
+- [`BPC_StatsTracker`](../11-polish/75_BPC_StatsTracker.md) — Stat aggregation
+- [`BPC_PlayerMetricsTracker`](../02-player/14_BPC_PlayerMetricsTracker.md) — Player action feed
+- [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) — Story progression events
+- [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) — Performance data
+
+### Purpose
+Anonymous gameplay analytics and telemetry tracker for development telemetry. Records anonymized player behavior, system performance, progression bottlenecks, and usage patterns. Designed for optional opt-in collection (GDPR/CCPA compliant). Outputs formatted JSON event logs to disk for developer analysis. Never collects personally identifiable information.
+
+### Enums
+
+**EAnalyticsEventType**
+
+| Value | Description |
+|-------|-------------|
+| Session | Session start/end |
+| Progression | Level/chapter events |
+| Combat | Enemy encounter data |
+| Death | Player death events |
+| Performance | FPS, load time data |
+| Settings | Options changed |
+| Crash | Game quit unexpectedly |
+| Achievement | Achievement earned |
+| Interaction | Object interaction |
+| Exploration | Zone discovery |
+
+**EAnalyticsPrivacyLevel**
+
+| Value | Description |
+|-------|-------------|
+| Full | All events |
+| Minimal | Session/progression only |
+| None | No tracking |
+
+### Structs
+
+**FAnalyticsEvent**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| EventID | FName | Event identifier |
+| EventType | EAnalyticsEventType | Category |
+| Timestamp | Float | Game time in seconds |
+| SessionID | FString | Unique session identifier |
+| DataPayload | TMap\<FString, FString\> | Event-specific data |
+| bAnonymized | Bool | No PII flag |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `bAnalyticsEnabled` | Bool | Master toggle |
+| `PrivacyLevel` | EAnalyticsPrivacyLevel | User consent level |
+| `SessionID` | FString | Unique session GUID |
+| `EventQueue` | TArray\<FAnalyticsEvent\> | Pending upload |
+| `QueueFlushInterval` | Float | Write to disk interval |
+| `bIsFlushing` | Bool | Currently writing |
+| `MaxQueueSize` | Int32 | Events before flush (50) |
+| `bIncludePerformance` | Bool | Performance telemetry |
+| `bIncludeSettings` | Bool | Settings telemetry |
+| `SessionStartTime` | Float | Session start timestamp |
+| `LastFlushTime` | Float | Last write timestamp |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Initialize` | — | — | Start session, load consent |
+| `RecordEvent` | Event: FAnalyticsEvent | — | Queue analytics event |
+| `RecordSessionStart` | — | — | Log new session |
+| `RecordSessionEnd` | — | — | Log session end |
+| `RecordProgressionEvent` | ChapterID: FName, Action: FString | — | Story progress |
+| `RecordCombatEvent` | EnemyType: FName, Result: FString | — | Combat outcome |
+| `RecordDeathEvent` | Cause: FString, Position: FVector | — | Death analytics |
+| `RecordPerformanceSnapshot` | FPS: Float, FrameTime: Float | — | Performance data |
+| `RecordSettingsChange` | Setting: FString, Value: FString | — | Settings telemetry |
+| `RecordInteraction` | ObjectID: FName, Action: FString | — | Interaction analytics |
+| `FlushEventQueue` | — | — | Write to disk |
+| `ClearEventQueue` | — | — | Discard unsent events |
+| `SetPrivacyLevel` | Level: EAnalyticsPrivacyLevel | — | Update consent |
+| `GenerateSessionID` | — | FString | Unique session GUID |
+| `GetTotalEventsRecorded` | — | Int32 | Event count |
+
+### Blueprint Flow
+
+```
+[Initialize]
+  └─► Load analytics consent from SS_SettingsManager
+  └─► If PrivacyLevel == None: bAnalyticsEnabled = false, return
+  └─► SessionID = GenerateSessionID()
+  └─► SessionStartTime = current game time
+  └─► RecordSessionStart()
+  └─► Start flush timer (QueueFlushInterval = 60 seconds)
+  └─► Bind event listeners:
+         BPC_PlayerMetricsTracker.OnEnemyKilled -> RecordCombatEvent
+         BPC_PlayerMetricsTracker.OnPlayerDeath -> RecordDeathEvent
+         BPC_NarrativeState.OnNarrativePhaseChanged -> RecordProgressionEvent
+         BPC_StatsTracker.OnStatUpdated -> Aggregate for session summary
+
+[RecordEvent]
+  └─► If Not bAnalyticsEnabled: return
+  └─► Event.Timestamp = GetGameTimeInSeconds()
+  └─► Event.SessionID = SessionID
+  └─► Event.bAnonymized = true
+  └─► If EventQueue.Length >= MaxQueueSize:
+         FlushEventQueue()
+  └─► EventQueue.Add(Event)
+
+[RecordSessionEnd]
+  └─► Create session summary event:
+         Total play time
+         Chapters completed
+         Deaths (from BPC_StatsTracker)
+         Total kills
+         Settings changed count
+         Performance averages
+  └─► RecordEvent(SessionSummary)
+  └─► FlushEventQueue()
+  └─► Broadcast OnSessionComplete(SessionID)
+
+[FlushEventQueue]
+  └─► If bIsFlushing OR EventQueue is empty: return
+  └─► bIsFlushing = true
+  └─► Serialize EventQueue to JSON string
+  └─► File name: "analytics_{SessionID}_{Timestamp}.json"
+  └─► Write to Saved/Analytics/ directory
+  └─► ClearEventQueue()
+  └─► bIsFlushing = false
+  └─► Log: "Analytics flushed: {Count} events"
+
+[SetPrivacyLevel]
+  └─► PrivacyLevel = Level
+  └─► If Level == None:
+         bAnalyticsEnabled = false
+         ClearEventQueue()
+         Delete all analytics files for this session
+  └─► Else if Level == Minimal:
+         bIncludePerformance = false
+         bIncludeSettings = false
+  └─► Else if Level == Full:
+         bIncludePerformance = true
+         bIncludeSettings = true
+  └─► Save consent to SS_SettingsManager
+
+[GenerateSessionID]
+  └─► Generate UUID/GUID string
+  └─► Format: "{timestamp}-{random-hex}"
+  └─► Return Session ID string
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnSessionComplete` | SessionID: FString | Session ended |
+| `OnPrivacyLevelChanged` | Level: EAnalyticsPrivacyLevel | Consent updated |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Save flush event |
+| [`BPC_StatsTracker`](../11-polish/75_BPC_StatsTracker.md) | Direct call | Aggregate stats |
+| [`BPC_PlayerMetricsTracker`](../02-player/14_BPC_PlayerMetricsTracker.md) | Event | Player actions |
+| [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) | Event | Progression events |
+| [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) | Event | Performance snapshots |
+| [`SS_SettingsManager`](../11-polish/71_SS_SettingsManager.md) | Direct call | Consent storage |
+
+### Reuse Notes
+- Fully opt-in with GDPR/CCPA-compliant consent levels
+- UUID-based session IDs — no PII collected
+- Events serialized to JSON for easy parsing
+- Queue-based flush system prevents disk spam
+- Separate analytics directory for clean file organization
+- Integrates with existing event dispatchers across all systems
+- Session summaries provide aggregate metrics
+- Privacy level change clears existing data immediately
--- a/docs/blueprints/13-polish/107_BPC_DevCheatManager.md
+++ b/docs/blueprints/13-polish/107_BPC_DevCheatManager.md
@@ -0,0 +1,187 @@
+# 80 — BPC_DevCheatManager
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`BPC_InventoryComponent`](../04-inventory/24_BPC_InventoryComponent.md) — Spawn items
+- [`BPC_Movement`](../02-player/10_BPC_Movement.md) — Toggle noclip/fly
+- [`BPC_HealthComponent`](../02-player/08_BPC_HealthComponent.md) — God mode, heal
+- [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) — Skip to chapter
+- [`BPC_TimeManager`](../01-core/02_BPC_TimeManager.md) — Time scale, pause
+- [`BPC_PlayerCamera`](../02-player/11_BPC_PlayerCamera.md) — Camera controls
+- [`BPC_FPSCounter`](../11-polish/79_BPC_FPSCounter.md) — Performance overlay
+- [`WBP_DebugMenu`](../11-polish/81_WBP_DebugMenu.md) — Visual debug UI
+- [`BPC_AudioManager`](../10-adaptive/66_BPC_AudioManager.md) — Audio debug
+- [`BPC_LightingManager`](../10-adaptive/65_BPC_LightingManager.md) — Lighting debug
+
+### Purpose
+Developer cheat and debug command manager for testing and development builds. Provides console commands and bound functions for common debug operations: god mode, noclip, spawning items, teleporting, time manipulation, AI debugging, narrative skipping, and performance profiling. Only active in non-shipping builds. Accessible via developer console (~) key or bound key combinations.
+
+### Enums
+
+**ECheatCategory**
+
+| Value | Description |
+|-------|-------------|
+| Player | Player-related cheats |
+| World | World manipulation |
+| AI | AI behavior debug |
+| Narrative | Story skip/advance |
+| Performance | Profiling tools |
+| Camera | Camera manipulation |
+| Inventory | Item spawning |
+| Debug | General debug toggles |
+
+### Structs
+
+**FCheatCommand**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| Command | FString | Console command string |
+| Category | ECheatCategory | Grouping |
+| Description | FText | Help text |
+| bRequiresAuth | Bool | Admin only |
+| bAvailableInShipping | Bool | Ship build flag |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `bCheatsEnabled` | Bool | Master toggle |
+| `bGodMode` | Bool | Invulnerability |
+| `bNoClipEnabled` | Bool | Fly/wall pass |
+| `bInfiniteAmmo` | Bool | Unlimited ammo |
+| `bInfiniteStamina` | Bool | Unlimited stamina |
+| `bInvisibleToAI` | Bool | AI ignore player |
+| `bShowAIDebug` | Bool | AI debug visualization |
+| `bShowCollision` | Bool | Collision wireframes |
+| `bShowPerformance` | Bool | Performance overlay |
+| `TimeScale` | Float | World time scale |
+| `RegisteredCommands` | TMap\<FString, FCheatCommand\> | Command registry |
+| `CheatHistory` | TArray\<FString\> | Command history |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Initialize` | — | — | Register all commands |
+| `EnableCheats` | bEnable: Bool | — | Master toggle |
+| `ExecuteCheat` | Command: FString, Args: TArray\<FString\> | — | Run cheat command |
+| `RegisterCommand` | Command: FCheatCommand | — | Add custom command |
+| `ToggleGodMode` | — | — | God mode on/off |
+| `ToggleNoClip` | — | — | Noclip on/off |
+| `ToggleInfiniteAmmo` | — | — | Infinite ammo |
+| `ToggleInfiniteStamina` | — | — | Infinite stamina |
+| `ToggleInvisibility` | — | — | AI invisibility |
+| `ToggleAIDebug` | — | — | AI visualization |
+| `ToggleCollisionDebug` | — | — | Collision vis |
+| `TogglePerformanceOverlay` | — | — | Show FPS/stats |
+| `ToggleDebugMenu` | — | — | Open debug menu |
+| `HealPlayer` | Amount: Float | — | Restore health |
+| `SetTimeScale` | Scale: Float | — | Slow-mo/speed-up |
+| `AddItem` | ItemID: FName, Count: Int32 | — | Spawn item |
+| `TeleportToLocation` | Location: FVector | — | Teleport player |
+| `TeleportToLevel` | LevelName: FName | — | Jump to level |
+| `SkipToChapter` | ChapterID: FName | — | Narrative skip |
+| `KillAllAIDebug` | — | — | Despawn all AI |
+| `SpawnAIDebug` | AIType: FName | — | Spawn AI for testing |
+| `GetAllCheatNames` | — | TArray\<FString\> | List all cheats |
+| `IsCheatEnabled` | CheatID: FName | Bool | State query |
+
+### Blueprint Flow
+
+```
+[Initialize]
+  └─► If BuildType == Shipping: Disable all, return
+  └─► Register default commands:
+         "God" -> ToggleGodMode
+         "NoClip" -> ToggleNoClip
+         "Fly" -> ToggleNoClip
+         "Ghost" -> ToggleNoClip + Invisibility
+         "Heal" -> HealPlayer(100)
+         "KillAll" -> KillAllAIDebug
+         "Slomo {value}" -> SetTimeScale(value)
+         "Summon {item}" -> AddItem
+         "Teleport {x} {y} {z}" -> TeleportToLocation
+         "Open {level}" -> TeleportToLevel
+         "Chapter {id}" -> SkipToChapter
+         "Stat FPS" -> TogglePerformanceOverlay
+         "DebugMenu" -> ToggleDebugMenu
+         "InfiniteAmmo" -> ToggleInfiniteAmmo
+         "Invisible" -> ToggleInvisibility
+  └─► bCheatsEnabled = true
+  └─► Bind to console input events
+
+[ExecuteCheat]
+  └─► Parse Command from input string
+  └─► Look up in RegisteredCommands
+  └─► If found:
+         Validate arguments
+         Execute bound function with args
+         Add to CheatHistory
+         Log: "Cheat: {Command}" (development builds only)
+  └─► If not found:
+         Log: "Unknown cheat command: {Command}"
+
+[ToggleGodMode]
+  └─► bGodMode = !bGodMode
+  └─► If bGodMode:
+         BPC_HealthComponent.SetInvulnerable(true)
+         Set health to max
+         Notify: "God mode ON"
+  └─► Else:
+         BPC_HealthComponent.SetInvulnerable(false)
+         Notify: "God mode OFF"
+
+[ToggleNoClip]
+  └─► bNoClipEnabled = !bNoClipEnabled
+  └─► If bNoClipEnabled:
+         BPC_Movement.SetMovementMode(Flying)
+         Disable collision with world
+         Notify: "NoClip ON"
+  └─► Else:
+         BPC_Movement.SetMovementMode(Walking)
+         Enable collision
+         Notify: "NoClip OFF"
+
+[SetTimeScale]
+  └─► TimeScale = Clamp(Scale, 0.1, 10.0)
+  └─► BPC_TimeManager.SetGlobalTimeDilation(TimeScale)
+  └─► Notify: "Time scale: {TimeScale}x"
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnCheatExecuted` | Command: FString | Command used |
+| `OnGodModeChanged` | bEnabled: Bool | God mode toggle |
+| `OnNoClipChanged` | bEnabled: Bool | NoClip toggle |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BPC_HealthComponent`](../02-player/08_BPC_HealthComponent.md) | Direct call | God mode |
+| [`BPC_Movement`](../02-player/10_BPC_Movement.md) | Direct call | NoClip |
+| [`BPC_InventoryComponent`](../04-inventory/24_BPC_InventoryComponent.md) | Direct call | Spawn items |
+| [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) | Direct call | Skip chapter |
+| [`BPC_TimeManager`](../01-core/02_BPC_TimeManager.md) | Direct call | Time scale |
+| [`BPC_FPSCounter`](../11-polish/79_BPC_FPSCounter.md) | Direct call | Performance overlay |
+| [`WBP_DebugMenu`](../11-polish/81_WBP_DebugMenu.md) | Create widget | Debug UI |
+| [`BPC_AIDirector`](../09-ai/57_BPC_AIDirector.md) | Direct call | AI debug |
+
+### Reuse Notes
+- Completely disabled in shipping builds via build flag check
+- All cheats are registered commands; extensible via RegisterCommand
+- Command history for repeated use
+- Cheat notifications shown via on-screen debug text
+- Supports both console and key binding input
+- Debug toggles are state-persistent across level transitions
+- Intended for development and QA team use only
--- a/docs/blueprints/13-polish/108_BPC_ErrorHandler.md
+++ b/docs/blueprints/13-polish/108_BPC_ErrorHandler.md
@@ -0,0 +1,221 @@
+# 83 — BPC_ErrorHandler
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Save state on error
+- [`BPC_LoadingScreen`](../11-polish/76_BPC_LoadingScreen.md) — Error screen display
+- [`BPC_AnalyticsTracker`](../11-polish/82_BPC_AnalyticsTracker.md) — Error telemetry
+- [`WBP_ErrorScreen`](../06-ui/49_WBP_ErrorScreen.md) — UI display (Phase 5)
+- [`BPC_LogManager`](../01-core/06_BPC_LogManager.md) — Logging (Phase 0)
+
+### Purpose
+Centralized error handling and crash recovery system. Traps and classifies runtime errors across all game systems, displays user-friendly error messages, attempts automatic recovery when possible, and provides fallback behaviors for non-critical failures. Supports error severity levels, recovery strategies, and persistent error logging. Prevents cascading failures by isolating errors to their originating system.
+
+### Enums
+
+**EErrorSeverity**
+
+| Value | Description |
+|-------|-------------|
+| Info | Non-critical, no action needed |
+| Warning | Minor issue, gameplay continues |
+| Error | Feature degraded, auto-recovery attempted |
+| Critical | Game cannot continue, autosave + return to menu |
+| Fatal | Crash/immediate shutdown |
+
+**EErrorSource**
+
+| Value | Description |
+|-------|-------------|
+| System | Core framework error |
+| SaveLoad | Save/load corruption |
+| Asset | Missing or corrupted asset |
+| Network | Network failure |
+| AI | AI system error |
+| Audio | Audio system error |
+| UI | Widget error |
+| Input | Input handling error |
+| Performance | Out of memory, hitch |
+| Unknown | Unclassified |
+
+**ERecoveryAction**
+
+| Value | Description |
+|-------|-------------|
+| None | No recovery needed |
+| Retry | Retry failed operation |
+| ResetSystem | Reinitialize subsystem |
+| ReloadLevel | Reload current level |
+| LoadLastSave | Load last checkpoint |
+| FallbackDefault | Use default values |
+| Terminate | End game session |
+
+### Structs
+
+**FErrorEntry**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| ErrorID | FName | Unique error identifier |
+| Severity | EErrorSeverity | Error level |
+| Source | EErrorSource | Originating system |
+| Message | FText | User-friendly description |
+| TechnicalDetails | FString | Developer details |
+| RecoveryAction | ERecoveryAction | Attempted recovery |
+| bRecoverySuccessful | Bool | Recovery outcome |
+| Timestamp | Float | When error occurred |
+| ContextData | TMap\<FName, FString\> | Error context |
+
+**FErrorThreshold**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| Source | EErrorSource | Error category |
+| MaxRetries | Int32 | Attempts before escalation |
+| RetryWindow | Float | Cooldown in seconds |
+| CurrentRetries | Int32 | Current attempt count |
+| LastErrorTime | Float | Last occurrence |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `bErrorHandlingEnabled` | Bool | Master toggle |
+| `ErrorLog` | TArray\<FErrorEntry\> | Persistent error history |
+| `ActiveError` | FErrorEntry | Current unhandled error |
+| `ErrorThresholds` | TMap\<EErrorSource, FErrorThreshold\> | Retry limits |
+| `bShowingErrorScreen` | Bool | UI displayed |
+| `bAutosaveOnError` | Bool | Save on critical error |
+| `bLogErrorsToFile` | Bool | Write error log |
+| `MaxLogSize` | Int32 | Error history cap (100) |
+| `RecoveryCallbacks` | TMap\<EErrorSource, Delegate\> | System recovery handlers |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Initialize` | — | — | Register default recovery handlers |
+| `HandleError` | Error: FErrorEntry | — | Process error entry |
+| `RegisterRecoveryHandler` | Source: EErrorSource, Callback: Delegate | — | Set recovery function |
+| `AttemptRecovery` | Error: FErrorEntry | Bool | Try to fix error |
+| `ShowErrorScreen` | Error: FErrorEntry | — | Display error UI |
+| `DismissErrorScreen` | — | — | Close error UI |
+| `LogError` | Error: FErrorEntry | — | Add to error log |
+| `GetErrorHistory` | Source: EErrorSource | TArray\<FErrorEntry\> | Filter errors |
+| `GetLastError` | — | FErrorEntry | Most recent error |
+| `ClearErrorLog` | — | — | Reset error history |
+| `CheckThreshold` | Source: EErrorSource | Bool | Retry limit reached |
+| `ResetThreshold` | Source: EErrorSource | — | Reset retry counter |
+| `HandleFatalError` | Error: FErrorEntry | — | Autosave + quit |
+| `RecoverSystem` | Source: EErrorSource | Bool | Reinitialize system |
+| `ReloadLevel` | — | — | Reload current level |
+| `LoadLastSave` | — | — | Rollback to save |
+| `RegisterSystemHealthCheck` | Name: FName, CheckFunc: Delegate | — | Periodic health |
+
+### Blueprint Flow
+
+```
+[Initialize]
+  └─► Register default recovery handlers:
+         EErrorSource.SaveLoad -> AttemptReadBackup()
+         EErrorSource.Asset -> LoadFallbackAsset()
+         EErrorSource.AI -> ResetAIDirector()
+         EErrorSource.Audio -> RebuildAudioEngine()
+         EErrorSource.UI -> RebuildWidgetTree()
+         EErrorSource.Input -> RebindInputContext()
+  └─► Start periodic health check timer (every 30 seconds)
+  └─► bErrorHandlingEnabled = true
+  └─► MaxLogSize = 100
+
+[HandleError]
+  └─► If Not bErrorHandlingEnabled: return (minimal logging via BPC_LogManager)
+  └─► Error.Timestamp = GetGameTimeInSeconds()
+  └─► LogError(Error)
+  └─► CheckThreshold(Error.Source):
+         If threshold exceeded:
+              Escalate severity one level
+              ResetThreshold(Error.Source)
+  └─► Switch Error.Severity:
+         Info: Log only, no action
+         Warning: Log + broadcast OnErrorOccurred
+         Error: Log + AttemptRecovery() + ShowErrorScreen if recovery fails
+         Critical: Autosave + AttemptRecovery() + LoadingScreen + Back to menu
+         Fatal: Autosave + ShowErrorScreen + Quit game after timer
+
+[AttemptRecovery]
+  └─► GetRecoveryHandler(Error.Source)
+  └─► If handler exists:
+         Execute handler
+         Error.RecoverySuccessful = result
+  └─► If Not recovery successful:
+         Increment threshold
+         If source is critical: escalate to HandleFatalError
+  └─► Broadcast OnRecoveryAttempted(Error.ErrorID, result)
+
+[HandleFatalError]
+  └─► If bAutosaveOnError: SS_SaveManager.QuickSave()
+  └─► ShowErrorScreen(Error):
+         Create WBP_ErrorScreen
+         Display error code, message
+         Show recovery options (Retry, Load Last Save, Quit)
+  └─► Set timer for auto-quit (10 seconds if no input)
+
+[LogError]
+  └─► ErrorLog.Add(Error)
+  └─► If ErrorLog.Length > MaxLogSize: Remove oldest entry
+  └─► Write to BPC_LogManager:
+         Error.Severity: Error log level
+         Message: TechnicalDetails
+  └─► If bLogErrorsToFile: Append to Saved/Errors/ErrorLog.txt
+
+[ShowErrorScreen]
+  └─► If bShowingErrorScreen: return (already displayed)
+  └─► bShowingErrorScreen = true
+  └─► Pause game
+  └─► Create WBP_ErrorScreen
+  └─► Set error code (ErrorID), description (Message)
+  └─► Show recovery buttons:
+         If recovery available: Retry button
+         If critical: Load Last Save, Quit buttons
+  └─► Add to viewport
+
+[DismissErrorScreen]
+  └─► If Not bShowingErrorScreen: return
+  └─► bShowingErrorScreen = false
+  └─► Remove WBP_ErrorScreen from viewport
+  └─► Resume game (unless transitioning to menu)
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnErrorOccurred` | Error: FErrorEntry | Any error trapped |
+| `OnRecoveryAttempted` | ErrorID: FName, bSuccess: Bool | Recovery result |
+| `OnFatalError` | Error: FErrorEntry | Unrecoverable error |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Autosave on critical |
+| [`BPC_LoadingScreen`](../11-polish/76_BPC_LoadingScreen.md) | Direct call | Error transition |
+| [`BPC_AnalyticsTracker`](../11-polish/82_BPC_AnalyticsTracker.md) | Direct call | Error telemetry |
+| [`WBP_ErrorScreen`](../06-ui/49_WBP_ErrorScreen.md) | Create widget | Error UI |
+| [`BPC_LogManager`](../01-core/06_BPC_LogManager.md) | Direct call | Logging |
+
+### Reuse Notes
+- Severity-based escalation prevents minor issues from interrupting gameplay
+- Retry thresholds with cooldown prevent infinite retry loops
+- Recovery handlers are registered per system; extensible architecture
+- Error screen gives player clear options instead of silent crash
+- Autosave on critical error protects player progress
+- Error log persists session errors for developer debugging
+- Health check system enables proactive error prevention
+- All error messages user-friendly; technical details separate for logs
--- a/docs/blueprints/13-polish/109_BPC_FPSCounter.md
+++ b/docs/blueprints/13-polish/109_BPC_FPSCounter.md
@@ -0,0 +1,186 @@
+# 79 — BPC_FPSCounter
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`WBP_FPSCounterWidget`](../06-ui/47_WBP_FPSCounterWidget.md) — UI display (Phase 5)
+- [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) — Quality auto-adjustment
+- [`SS_SettingsManager`](../11-polish/71_SS_SettingsManager.md) — Show FPS toggle
+- [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) — Debug overlay toggle
+
+### Purpose
+Performance monitoring component that calculates and displays real-time FPS (frames per second), frame time, and other performance metrics. Supports configurable update intervals, color-coded thresholds (green/yellow/red), on-screen display toggle, and optional system statistics (CPU/GPU time, memory usage). Provides performance data to auto-scaling systems and developer debugging tools.
+
+### Enums
+
+**EFPSDisplayMode**
+
+| Value | Description |
+|-------|-------------|
+| Off | Hidden |
+| Simple | FPS only |
+| Detailed | FPS + frame time |
+| Full | FPS + frame time + CPU/GPU |
+| Profiling | Full + memory + draw calls |
+
+**EFPSStatusColor**
+
+| Value | Description |
+|-------|-------------|
+| Good | FPS >= 60 |
+| Warning | FPS 30–59 |
+| Critical | FPS < 30 |
+
+### Structs
+
+**FPerformanceMetrics**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| CurrentFPS | Float | Frames per second |
+| AverageFPS | Float | Smoothed average |
+| MinFPS | Float | Lowest this session |
+| MaxFPS | Float | Highest this session |
+| FrameTime | Float | Delta time in ms |
+| CPUTime | Float | CPU frame time ms |
+| GPUTime | Float | GPU frame time ms |
+| UsedMemoryMB | Float | Memory usage |
+| DrawCalls | Int32 | Current draw calls |
+| TriangleCount | Int32 | Rendered triangles |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `DisplayMode` | EFPSDisplayMode | Current display level |
+| `UpdateInterval` | Float | Seconds between updates (default 0.25) |
+| `AccumulatedTime` | Float | Timer accumulator |
+| `FrameCount` | Int32 | Frames counted |
+| `CurrentMetrics` | FPerformanceMetrics | Latest snapshot |
+| `StatusColor` | EFPSStatusColor | Color threshold |
+| `bIsVisible` | Bool | HUD element shown |
+| `FPSCounterWidget` | WBP_FPSCounterWidget | UI reference |
+| `SmoothFPS` | Float | Exponentially smoothed |
+| `Alpha` | Float | Smoothing factor (0.05) |
+| `PerformanceHistory` | TArray\<Float\> | Last 60 FPS values |
+| `GoodThreshold` | Int32 | FPS for green (60) |
+| `WarningThreshold` | Int32 | FPS for yellow (30) |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Initialize` | — | — | Setup timers, bind settings |
+| `ToggleDisplay` | — | — | Show/hide FPS |
+| `SetDisplayMode` | Mode: EFPSDisplayMode | — | Change detail level |
+| `SetUpdateInterval` | Interval: Float | — | Change update rate |
+| `CalculateFPS` | DeltaTime: Float | — | Compute metrics |
+| `GetCurrentFPS` | — | Float | Latest FPS |
+| `GetAverageFPS` | — | Float | Session average |
+| `GetStatusColor` | FPS: Float | EFPSStatusColor | Threshold check |
+| `UpdateDisplay` | — | — | Refresh widget |
+| `GetPerformanceSnapshot` | — | FPerformanceMetrics | Full metrics |
+| `GetMinFPS` | — | Float | Session minimum |
+| `GetMaxFPS` | — | Float | Session maximum |
+| `ResetMetrics` | — | — | Clear session stats |
+| `LogPerformanceWarning` | FPS: Float | — | Log low FPS event |
+
+### Blueprint Flow
+
+```
+[Initialize]
+  └─► If Not HasAuthority: return (client only)
+  └─► DisplayMode = Simple (default)
+  └─► SmoothFPS = 0
+  └─► GoodThreshold = 60, WarningThreshold = 30
+  └─► Create WBP_FPSCounterWidget
+  └─► Add to viewport (small, top-right corner, auto-z-order)
+  └─► bIsVisible = false
+  └─► Bind to SS_SettingsManager:
+         OnSettingChanged("ShowFPS") -> ToggleDisplay()
+
+[Tick / CalculateFPS]
+  └─► If Not bIsVisible: return
+  └─► AccumulatedTime += DeltaTime
+  └─► FrameCount++
+  └─► If AccumulatedTime >= UpdateInterval:
+         CurrentMetrics.CurrentFPS = FrameCount / AccumulatedTime
+         SmoothFPS = (Alpha * CurrentFPS) + (1 - Alpha) * SmoothFPS
+         CurrentMetrics.AverageFPS = SmoothFPS
+         CurrentMetrics.FrameTime = (AccumulatedTime / FrameCount) * 1000
+         // Track min/max
+         If CurrentFPS < MinFPS: MinFPS = CurrentFPS
+         If CurrentFPS > MaxFPS: MaxFPS = CurrentFPS
+         // Status color
+         StatusColor = GetStatusColor(SmoothFPS)
+         // Update history
+         PerformanceHistory.Add(SmoothFPS)
+         If PerformanceHistory.Length > 60: Remove oldest
+         // Log warning if critical
+         If SmoothFPS < WarningThreshold:
+              LogPerformanceWarning(SmoothFPS)
+         // Update widget
+         UpdateDisplay()
+         // Reset counters
+         AccumulatedTime = 0
+         FrameCount = 0
+
+[UpdateDisplay]
+  └─► If Not bIsVisible OR Not FPSCounterWidget: return
+  └─► Switch DisplayMode:
+         Simple: Set text "FPS: {SmoothFPS}" (integer)
+         Detailed: "FPS: {SmoothFPS} | {FrameTime}ms"
+         Full: "FPS | FrameTime | CPU | GPU"
+         Profiling: Full stats + memory + draw calls
+  └─► Set text color based on StatusColor:
+         Good -> Green
+         Warning -> Yellow
+         Critical -> Red
+  └─► Widget update complete
+
+[ToggleDisplay]
+  └─► bIsVisible = !bIsVisible
+  └─► If bIsVisible:
+         FPSCounterWidget.SetVisibility(Visible)
+  └─► Else:
+         FPSCounterWidget.SetVisibility(Collapsed)
+         AccumulatedTime = 0
+         FrameCount = 0
+
+[ResetMetrics]
+  └─► CurrentMetrics.MinFPS = max float
+  └─► CurrentMetrics.MaxFPS = 0
+  └─► PerformanceHistory.Empty()
+  └─► AccumulatedTime = 0
+  └─► FrameCount = 0
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnPerformanceWarning` | FPS: Float, StatusColor: EFPSStatusColor | Low FPS detected |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`WBP_FPSCounterWidget`](../06-ui/47_WBP_FPSCounterWidget.md) | Widget reference | UI display |
+| [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) | Event | Auto-adjust quality |
+| [`SS_SettingsManager`](../11-polish/71_SS_SettingsManager.md) | Event | Toggle from settings |
+| [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) | Direct call | Debug overlay |
+
+### Reuse Notes
+- Uses exponential smoothing for stable readout
+- Color-coded thresholds for quick visual assessment
+- Configurable update interval reduces overhead
+- Multiple display modes for different needs
+- Performance history tracks last 60 samples
+- Min/Max tracking for session analysis
+- Toggle via settings menu or developer console
+- Lightweight; only updates on tick at configured interval
--- a/docs/blueprints/13-polish/110_BPC_LoadingScreen.md
+++ b/docs/blueprints/13-polish/110_BPC_LoadingScreen.md
@@ -0,0 +1,169 @@
+# 76 — BPC_LoadingScreen
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Load state during transitions
+- [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) — Quality level for loading assets
+- [`WBP_LoadingScreen`](../06-ui/46_WBP_LoadingScreen.md) — UI widget (Phase 5)
+- [`FL_LevelStreaming`](../01-core/07_FL_LevelStreaming.md) — Level loading utilities (Phase 0)
+- [`DA_LoadingTips`](../12-content/79_DA_LoadingTips.md) — Tip data assets (Phase 12)
+
+### Purpose
+Manages loading screen display and behavior during level transitions, save/load operations, and streaming scenarios. Controls visibility, progress feedback, tip rotation, background presentation, and minimum display duration. Supports seamless transitions with fade effects and asynchronous loading state tracking.
+
+### Enums
+
+**ELoadingScreenType**
+
+| Value | Description |
+|-------|-------------|
+| LevelTransition | Full level load |
+| SaveLoad | Save/load operation |
+| Streaming | Sub-level streaming |
+| Boot | Initial game load |
+| Quick | Fast travel |
+
+**ELoadingScreenState**
+
+| Value | Description |
+|-------|-------------|
+| Inactive | No loading active |
+| FadingIn | Fade to black |
+| Visible | Loading displayed |
+| FadingOut | Fade from black |
+| Complete | Load done, cleanup |
+
+### Structs
+
+**FLoadingScreenConfig**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| Type | ELoadingScreenType | What triggered this |
+| bShowTips | Bool | Rotate loading tips |
+| bShowProgress | Bool | Show progress bar |
+| bUseBackgroundImage | Bool | Static or image |
+| MinDisplayTime | Float | Minimum seconds shown |
+| FadeInDuration | Float | Fade to black time |
+| FadeOutDuration | Float | Fade from black time |
+| BackgroundImages | TArray\<UTexture2D\> | Optional backgrounds |
+| bAllowSkipping | Bool | Skip after load complete |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `CurrentState` | ELoadingScreenState | Current loading state |
+| `CurrentConfig` | FLoadingScreenConfig | Active configuration |
+| `LoadingScreenWidget` | WBP_LoadingScreen | Widget reference |
+| `LoadStartTime` | Float | When load began |
+| `bIsTransitioning` | Bool | Fade in progress |
+| `RemainingTips` | TArray\<FText\> | Unshown tips pool |
+| `BackgroundIndex` | Int32 | Current background |
+| `bLoadingComplete` | Bool | Load finished flag |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `ShowLoadingScreen` | Type: ELoadingScreenType, Config: FLoadingScreenConfig | — | Start loading display |
+| `HideLoadingScreen` | — | — | End loading display |
+| `UpdateLoadingProgress` | Progress: Float, StatusText: FText | — | Update progress bar |
+| `SetLoadingMessage` | Message: FText | — | Change message text |
+| `GetNextTip` | — | FText | Get random tip |
+| `GetNextBackground` | — | UTexture2D | Cycle backgrounds |
+| `SetBootConfiguration` | — | — | Configure for initial load |
+| `SetLevelTransitionConfig` | LevelName: FName | — | Configure for level load |
+| `HandleFadeInComplete` | — | — | Fade in finished |
+| `HandleFadeOutComplete` | — | — | Fade out finished |
+| `ForceCompleteLoading` | — | — | Skip remaining time |
+| `ProcessPendingLoading` | — | — | Handle load queue |
+| `LogLoadingComplete` | LoadTime: Float | — | Log load duration |
+
+### Blueprint Flow
+
+```
+[ShowLoadingScreen]
+  └─► If bIsTransitioning: return (queue if needed)
+  └─► Set CurrentConfig = Config
+  └─► LoadStartTime = Current Time
+  └─► FadeIn:
+         Create WBP_LoadingScreen
+         Add to viewport (topmost Z-order)
+         Play fade in animation (FadeInDuration)
+         On anim complete:
+              CurrentState = Visible
+              bIsTransitioning = false
+  └─► If Type == Boot:
+         Show game logo, company logo (fade sequence)
+  └─► Start rotating tips timer (every 8 seconds):
+         GetNextTip() -> Update loading message
+  └─► If bUseBackgroundImage:
+         Set static or rotating backgrounds
+
+[UpdateLoadingProgress]
+  └─► If Not Visible: return
+  └─► Clamp Progress 0–1
+  └─► WBP_LoadingScreen.UpdateProgress(Progress, StatusText)
+
+[HideLoadingScreen]
+  └─► If Complete animation not playing && elapsed < MinDisplayTime:
+         Delay until MinDisplayTime reached
+  └─► CurrentState = FadingOut
+  └─► bIsTransitioning = true
+  └─► Play fade out animation (FadeOutDuration)
+  └─► On anim complete:
+         Remove WBP_LoadingScreen from viewport
+         CurrentState = Inactive
+         bIsTransitioning = false
+         LogLoadingComplete(ElapsedTime)
+         Broadcast OnLoadingComplete()
+
+[GetNextTip]
+  └─► If RemainingTips is empty:
+         Refill from DA_LoadingTips
+  └─► Remove random tip from RemainingTips
+  └─► Return tip text
+
+[Level Transition Flow]
+  └─► Level requested
+  └─► ShowLoadingScreen(LevelTransition)
+  └─► Asynchronous level loading:
+         Bind to load progress delegate
+         UpdateLoadingProgress(Progress, "Loading...")
+  └─► Level fully loaded:
+         Set bLoadingComplete = true
+         HideLoadingScreen()
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnLoadingStarted` | Type: ELoadingScreenType | Load began |
+| `OnLoadingComplete` | — | Load finished, fade out |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`WBP_LoadingScreen`](../06-ui/46_WBP_LoadingScreen.md) | Widget reference | Display control |
+| [`FL_LevelStreaming`](../01-core/07_FL_LevelStreaming.md) | Direct call | Level load progress |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Save/load operations |
+| [`BPC_PerformanceScaler`](../10-adaptive/68_BPC_PerformanceScaler.md) | Direct call | Quality during load |
+| [`DA_LoadingTips`](../12-content/79_DA_LoadingTips.md) | Data asset | Tip content |
+
+### Reuse Notes
+- Config-driven for different loading contexts (boot, level, save)
+- Tip rotation prevents repetition during long loads
+- MinDisplayTime prevents flash-loading on fast systems
+- Background cycling adds visual variety
+- Fade in/out duration configurable per context
+- Asynchronous progress bound to actual load completion
+- Compatible with both synchronous and async level loading
--- a/docs/blueprints/13-polish/111_BPC_TutorialSystem.md
+++ b/docs/blueprints/13-polish/111_BPC_TutorialSystem.md
@@ -0,0 +1,196 @@
+# 73 — BPC_TutorialSystem
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`ActorComponent`
+
+### Dependencies
+- [`SS_SettingsManager`](71_SS_SettingsManager.md) — Tutorial enabled setting
+- [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) — Tutorial gating
+- [`WBP_TutorialOverlay`](../06-ui/47_WBP_TutorialOverlay.md) — Tutorial UI display
+- [`DA_TutorialData`](../12-content/77_DA_TutorialData.md) — Tutorial content definitions (Phase 12)
+
+### Purpose
+Manages contextual tutorial prompts, guided first-time experiences, and hint systems. Tracks which tutorials the player has seen, what actions they have performed, and shows relevant tips at appropriate moments. Supports contextual triggers (player performs action for first time), zone-based triggers (player enters new area), and manual triggers (player opens tutorial menu).
+
+### Enums
+
+**ETutorialTriggerType**
+
+| Value | Description |
+|-------|-------------|
+| OnFirstAction | Player performs action for first time |
+| OnEnterZone | Player enters tutorial zone volume |
+| OnItemPickup | Player picks up key item first time |
+| OnEncounterFirstEnemy | First enemy encounter |
+| OnManualOpen | Player opens tutorial from menu |
+| OnProximityToObject | Near specific interactable |
+| OnNarrativePhase | Story progression trigger |
+| OnSkillUnlock | Player unlocks ability |
+
+**ETutorialDisplayStyle**
+
+| Value | Description |
+|-------|-------------|
+| FullScreen | Large overlay with detailed instructions |
+| Panel | Bottom-right panel with image and text |
+| Tooltip | Small floating hint near relevant object |
+| Toast | Brief notification that auto-dismisses |
+| Interactive | Step-by-step guided tutorial |
+
+### Structs
+
+**FTutorialEntry**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| TutorialID | FName | Unique identifier |
+| Title | FText | Tutorial title |
+| Description | FText | Tutorial body text |
+| DisplayStyle | ETutorialDisplayStyle | How to show |
+| TriggerType | ETutorialTriggerType | Activation condition |
+| bIsMandatory | Bool | Must complete to proceed |
+| bCanBeSkipped | Bool | Player can dismiss |
+| Priority | Int32 | Display priority |
+| CooldownSeconds | Float | Min time before showing again |
+| Image | UTexture2D | Optional illustration |
+| InputActionShown | FName | Action key to highlight |
+| RelatedTutorials | TArray\<FName\> | Chain of tutorials |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `CompletedTutorials` | TSet\<FName\> | Tutorials player has completed |
+| `SeenTutorials` | TSet\<FName\> | Tutorials shown this playthrough |
+| `PendingTutorials` | TArray\<FTutorialEntry\> | Queue of tutorials to show |
+| `ActiveTutorial` | FTutorialEntry | Currently displayed |
+| `bTutorialActive` | Bool | Currently showing tutorial |
+| `bTutorialsEnabled` | Bool | Global toggle |
+| `bSkipAllTutorials` | Bool | Speedrun mode |
+| `FirstActionTracker` | TMap\<FName, bool\> | Track first-time actions |
+| `ZoneTracker` | TMap\<FName, bool\> | Track visited zones |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `Initialize` | — | — | Load completed tutorials from save |
+| `RegisterTutorial` | Entry: FTutorialEntry | — | Add tutorial to registry |
+| `TriggerTutorial` | TutorialID: FName | — | Force show tutorial |
+| `TriggerTutorialByType` | Trigger: ETutorialTriggerType, Context: FName | — | Contextual trigger |
+| `CompleteTutorial` | TutorialID: FName | — | Mark as completed |
+| `DismissTutorial` | — | — | Close active tutorial |
+| `SkipTutorial` | — | — | Skip current tutorial |
+| `GetNextTutorialInChain` | TutorialID: FName | FName | Get related tutorial |
+| `ShowTutorialOverlay` | Entry: FTutorialEntry | — | Display tutorial UI |
+| `HideTutorialOverlay` | — | — | Close tutorial UI |
+| `IsTutorialCompleted` | TutorialID: FName | Bool | Check completion |
+| `HasTutorialBeenSeen` | TutorialID: FName | Bool | Check if shown |
+| `OnFirstAction` | ActionName: FName | — | Track first action |
+| `OnEnterZone` | ZoneName: FName | — | Track zone entry |
+| `RegisterFirstActionTutorials` | — | — | Register common action tutorials |
+| `RegisterZoneTutorials` | — | — | Register zone tutorials |
+| `ProcessPendingQueue` | — | — | Show next queued tutorial |
+| `SaveTutorialState` | — | — | Persist to save system |
+
+### Blueprint Flow
+
+```
+[Initialize]
+  └─► Load CompletedTutorials from save data
+  └─► RegisterFirstActionTutorials()
+  └─► RegisterZoneTutorials()
+  └─► Listen to events:
+         BPC_HealthSystem.OnHealthChanged (first damage)
+         BPC_InventoryComponent.OnItemAdded (first pickup)
+         BPC_InteractDetector.OnInteraction (first interact)
+         BPC_Combat.OnFirstAttack (first attack)
+         BPC_ProceduralEncounter.OnEncounterStarted (first combat)
+
+[OnFirstAction]
+  └─► If FirstActionTracker[ActionName] == true: return (already tracked)
+  └─► FirstActionTracker[ActionName] = true
+  └─► Look up tutorial with TriggerType == OnFirstAction and Context == ActionName
+  └─► If found and not completed:
+         TriggerTutorial(TutorialID)
+
+[TriggerTutorial]
+  └─► If bSkipAllTutorials or not bTutorialsEnabled: return
+  └─► If IsTutorialCompleted(TutorialID): return
+  └─► If bTutorialActive:
+         Add to PendingTutorials queue
+         Return
+  └─► Get FTutorialEntry from registry
+  └─► ActiveTutorial = Entry
+  └─► bTutorialActive = true
+  └─► SeenTutorials.Add(TutorialID)
+  └─► ShowTutorialOverlay(Entry)
+  └─► If bIsMandatory:
+         Pause game and force focus
+  └─► Start cooldown timer for auto-dismiss
+
+[ShowTutorialOverlay]
+  └─► Based on DisplayStyle:
+         FullScreen:  Create WBP_TutorialFullScreen, add to viewport
+         Panel:       Create WBP_TutorialPanel, add to viewport corner
+         Tooltip:     Create WBP_TutorialTooltip, attach to relevant actor
+         Toast:       Create WBP_TutorialToast, auto-dismiss after 5 seconds
+         Interactive: Create WBP_InteractiveTutorial, step-by-step guide
+  └─► Set tutorial text, title, image
+  └─► If InputActionShown is set:
+         Highlight the key in on-screen prompts
+
+[CompleteTutorial]
+  └─► CompletedTutorials.Add(TutorialID)
+  └─► SeenTutorials.Add(TutorialID)
+  └─► HideTutorialOverlay()
+  └─► bTutorialActive = false
+  └─► SaveTutorialState()
+  └─► ProcessPendingQueue()
+
+[ProcessPendingQueue]
+  └─► If PendingTutorials.Num() > 0:
+         Sort by Priority descending
+         Next = PendingTutorials[0]
+         PendingTutorials.RemoveAt(0)
+         TriggerTutorial(Next.TutorialID)
+
+[DismissTutorial]
+  └─► If ActiveTutorial.bCanBeSkipped or not bIsMandatory:
+         HideTutorialOverlay()
+         bTutorialActive = false
+         ProcessPendingQueue()
+
+[SaveTutorialState]
+  └─► Serialize CompletedTutorials to array
+  └─► Call SS_SaveManager.SavePersistentData("Tutorials", CompletedTutorialsArray)
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnTutorialStarted` | TutorialID: FName, Title: FText | Tutorial began |
+| `OnTutorialCompleted` | TutorialID: FName | Tutorial finished |
+| `OnTutorialDismissed` | TutorialID: FName, bWasSkipped: Bool | Tutorial closed |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`SS_SettingsManager`](71_SS_SettingsManager.md) | Direct call | Tutorial enabled check |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Persist tutorial state |
+| [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) | Event | Narrative-gated tutorials |
+| [`WBP_TutorialOverlay`](../06-ui/47_WBP_TutorialOverlay.md) | Create widget | Display tutorials |
+| [`BP_PlayerController`] | Cast | Pause game for mandatory |
+
+### Reuse Notes
+- Tutorials are data-driven via FTutorialEntry — easy to add new ones
+- First-action tracking uses FName keys for extensibility
+- Queue system prevents tutorials from overlapping
+- Skip option for speedrunners and repeat playthroughs
+- State persists across save/load so tutorials don't repeat
--- a/docs/blueprints/13-polish/112_WBP_CreditsScreen.md
+++ b/docs/blueprints/13-polish/112_WBP_CreditsScreen.md
@@ -0,0 +1,175 @@
+# 77 — WBP_CreditsScreen
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`UserWidget`
+
+### Dependencies
+- [`BPC_InputManager`](../02-player/13_BPC_InputManager.md) — Skip input handling
+- [`BPC_AudioManager`](../10-adaptive/66_BPC_AudioManager.md) — Credit music/ambience
+- [`BPC_LoadingScreen`](../11-polish/76_BPC_LoadingScreen.md) — Post-credits transition
+- [`DA_CreditsData`](../12-content/80_DA_CreditsData.md) — Credit entries (Phase 12)
+
+### Purpose
+Animated credits display shown at game completion. Renders scrolling credit entries with sections (department headings, names, roles), supports speed control, pause/resume, and skip. Includes fade-in/out transitions and supports both standard and post-credits scenes. Designed to feel cinematic with smooth scrolling text.
+
+### Enums
+
+**ECreditSectionType**
+
+| Value | Description |
+|-------|-------------|
+| Title | Main title text |
+| Department | Group heading |
+| Name | Person/role entry |
+| Divider | Separator line |
+| Special | Custom styled entry |
+| Logo | Company logo display |
+
+### Structs
+
+**FCreditEntry**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| SectionType | ECreditSectionType | Entry category |
+| Text | FText | Display text |
+| SubText | FText | Role or subtitle |
+| DelaySeconds | Float | Extra pause before |
+| FontScale | Float | Size multiplier |
+| bBold | Bool | Bold style |
+| LogoTexture | UTexture2D | Optional logo |
+
+**FCreditsSection**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| SectionHeading | FText | Department name |
+| Entries | TArray\<FCreditEntry\> | People in section |
+| bSeparator | Bool | Add line after |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `CreditsData` | FCreditsSection[] | Full credit sequence |
+| `CurrentEntryIndex` | Int32 | Active entry |
+| `ScrollSpeed` | Float | Pixels per second |
+| `bIsPlaying` | Bool | Credits running |
+| `bIsPaused` | Bool | User paused |
+| `bSkippable` | Bool | Allow skip |
+| `TotalEntries` | Int32 | End of list marker |
+| `AccumulatedTime` | Float | Entry transition timer |
+| `bFadeComplete` | Bool | Intro finished |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `InitializeCredits` | Data: FCreditsSection[] | — | Set up display |
+| `PlayCredits` | — | — | Start scrolling |
+| `PauseCredits` | — | — | Pause scrolling |
+| `ResumeCredits` | — | — | Resume scrolling |
+| `SkipCredits` | — | — | End credits early |
+| `SetScrollSpeed` | Speed: Float | — | Adjust speed |
+| `ShowNextEntry` | — | — | Display next credit |
+| `ShowPreviousEntry` | — | — | Display previous |
+| `FadeInScreen` | — | — | Intro animation |
+| `FadeOutScreen` | — | — | Outro animation |
+| `OnCreditsComplete` | — | — | End of credits |
+| `HandleInputAction` | Action: FName | — | Input binding |
+| `GetSectionsForCollectibles` | — | FCreditsSection[] | Unlockable content credits |
+
+### Blueprint Flow
+
+```
+[InitializeCredits]
+  └─► Clear all existing entries
+  └─► CurrentEntryIndex = 0
+  └─► Load CreditsData from DA_CreditsData
+  └─► If player collected all collectibles:
+         Add bonus sections (GetSectionsForCollectibles)
+  └─► TotalEntries = Sum of all entries
+
+[PlayCredits]
+  └─► If already playing: return
+  └─► bIsPlaying = true
+  └─► FadeInScreen()
+         Set widget opacity 0 → 1 over 1.5 seconds
+         On fade complete: bFadeComplete = true
+  └─► Start scrolling:
+         Every Tick:
+              If bIsPaused: return
+              AccumulatedTime += DeltaTime * ScrollSpeed
+              If AccumulatedTime >= EntryDisplayThreshold:
+                   ShowNextEntry()
+                   AccumulatedTime = 0
+
+[ShowNextEntry]
+  └─► If CurrentEntryIndex >= TotalEntries:
+         OnCreditsComplete()
+         Return
+  └─► Current Credit = CreditsData entries[CurrentEntryIndex]
+  └─► Create text block with appropriate styling:
+         Title: large, centered, bold
+         Department: medium, uppercase, separated
+         Name: normal, two-column layout
+         Divider: thin line, 50% width
+  └─► Apply fade-in animation on new entry
+  └─► Fade out previous entry
+  └─► CurrentEntryIndex++
+
+[OnCreditsComplete]
+  └─► bIsPlaying = false
+  └─► FadeOutScreen()
+         Set widget opacity 1 → 0 over 2 seconds
+  └─► On fade complete:
+         Broadcast OnCreditsFinished()
+         If bReturnToMenu:
+              Load main menu level
+         Else:
+              Trigger post-credits content
+
+[SkipCredits]
+  └─► If Not bSkippable: return
+  └─► bIsPlaying = false
+  └─► Immediate fade out (0.3 seconds)
+  └─► Broadcast OnCreditsSkipped()
+  └─► Proceed to post-credits flow
+
+[HandleInputAction]
+  └─► Bind to BPC_InputManager:
+         "Pause" -> Toggle Pause/Resume
+         "Skip" -> SkipCredits()
+         "SpeedUp" -> SetScrollSpeed(1.5x)
+         "SlowDown" -> SetScrollSpeed(0.5x)
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnCreditsFinished` | — | Normal completion |
+| `OnCreditsSkipped` | — | User skipped |
+| `OnCreditsPaused` | — | Paused state |
+| `OnCreditsResumed` | — | Resumed state |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BPC_InputManager`](../02-player/13_BPC_InputManager.md) | Event binding | Input handling |
+| [`BPC_AudioManager`](../10-adaptive/66_BPC_AudioManager.md) | Direct call | Music/ambience |
+| [`BPC_LoadingScreen`](../11-polish/76_BPC_LoadingScreen.md) | Direct call | Post-credits transition |
+| [`DA_CreditsData`](../12-content/80_DA_CreditsData.md) | Data asset | Credit entries |
+
+### Reuse Notes
+- Entirely data-driven via DA_CreditsData
+- Supports unlockable post-credits content based on collectibles
+- Scroll speed configurable and allows speed-up
+- Pause/Resume supports accessibility needs
+- Clean separation of data and presentation
+- Can be reused for splash screens, acknowledgments, or prologue credit sequences
--- a/docs/blueprints/13-polish/113_WBP_DebugMenu.md
+++ b/docs/blueprints/13-polish/113_WBP_DebugMenu.md
@@ -0,0 +1,141 @@
+# 81 — WBP_DebugMenu
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`UserWidget`
+
+### Dependencies
+- [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) — Cheat execution
+- [`BPC_PlayerCamera`](../02-player/11_BPC_PlayerCamera.md) — Camera controls
+- [`BPC_FPSCounter`](../11-polish/79_BPC_FPSCounter.md) — Performance display
+- [`BPC_AIDirector`](../09-ai/57_BPC_AIDirector.md) — AI debug panel
+- [`BPC_DynamicEventSystem`](../10-adaptive/67_BPC_DynamicEventSystem.md) — Event debug
+- [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) — Story state viewer
+
+### Purpose
+Visual debug overlay menu for developers and QA testers. Provides categorized panels for toggling debug features, viewing runtime state (narrative, AI, events, inventory), adjusting world settings (time scale, lighting), and executing cheat commands from a user-friendly UI. Accessible via the ~ console toggle or from the BPC_DevCheatManager. Only available in non-shipping builds.
+
+### Enums
+
+**EDebugPanel**
+
+| Value | Description |
+|-------|-------------|
+| Main | Top-level menu |
+| Cheats | Cheat toggles |
+| Performance | FPS, memory, draw calls |
+| AI | AI state and debug vis |
+| Narrative | Quest/chapter state |
+| World | Time, lighting, weather |
+| Camera | Camera modes |
+| Inventory | Item list and manipulation |
+| Events | Dynamic event state |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `Panels` | TMap\<EDebugPanel, UUserWidget\> | Sub-panel references |
+| `ActivePanel` | EDebugPanel | Currently visible |
+| `bIsOpen` | Bool | Menu visible |
+| `bMinimized` | Bool | Compact view |
+| `DebugConsoleText` | FText | Command input |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `OpenMenu` | — | — | Show debug menu |
+| `CloseMenu` | — | — | Hide debug menu |
+| `ToggleMenu` | — | — | Open/close |
+| `SwitchPanel` | Panel: EDebugPanel | — | Change active panel |
+| `GetMinimumView` | — | — | Compact mode |
+| `ExecuteCommandFromUI` | Command: FString | — | Run cheat |
+| `UpdateAIDebugDisplay` | — | — | Refresh AI info |
+| `UpdatePerformanceDisplay` | Metrics: FPerformanceMetrics | — | Refresh FPS/stats |
+| `UpdateNarrativeStateDisplay` | — | — | Show story state |
+| `UpdateEventStateDisplay` | — | — | Show event state |
+| `ToggleGodModeUI` | — | — | Toggle from UI |
+| `ToggleNoClipUI` | — | — | Toggle from UI |
+| `ToggleCollisionDebug` | — | — | Toggle from UI |
+| `ToggleAIVisibility` | — | — | Toggle from UI |
+| `SetTimeScaleFromUI` | Scale: Float | — | Slider control |
+| `SpawnItemFromUI` | ItemID: FString | — | Drop-down spawn |
+| `SkipToChapterFromUI` | ChapterID: FString | — | Drop-down skip |
+
+### Blueprint Flow
+
+```
+[OpenMenu]
+  └─► If bIsOpen: return
+  └─► bIsOpen = true
+  └─► Set input mode: GameAndUI (mouse cursor visible)
+  └─► SetVisibility(Visible)
+  └─► Default panel: Main
+  └─► Pause game time (optional)
+  └─► Bind keyboard shortcuts:
+         Tab -> SwitchPanel(next)
+         Esc -> CloseMenu
+         F1 -> Cheats, F2 -> Performance, F3 -> AI
+         F4 -> Narrative, F5 -> World, F6 -> Camera
+
+[CloseMenu]
+  └─► bIsOpen = false
+  └─► Set input mode: GameOnly
+  └─► SetVisibility(Collapsed)
+  └─► Resume game time (if paused)
+
+[SwitchPanel]
+  └─► Hide all sub-panels
+  └─► ActivePanel = Panel
+  └─► Show corresponding sub-panel
+  └─► Update displayed data:
+         Performance -> Call BPC_FPSCounter.GetPerformanceSnapshot()
+         AI -> Call BPC_AIDirector.GetDebugState()
+         Narrative -> Call BPC_NarrativeState.GetCurrentChapter()
+         Events -> Call BPC_DynamicEventSystem.GetActiveEvents()
+
+[UI Layout]
+  └─► Left sidebar: Panel selection buttons
+  └─► Main content: Active panel content
+  └─► Bottom bar: Command input field + Execute button + Minimize
+  └─► Top bar: Indices for quick-nav, FPS counter overlay
+
+[ExecuteCommandFromUI]
+  └─► Get text from command input field
+  └─► Pass to BPC_DevCheatManager.ExecuteCheat()
+  └─► Clear input field
+  └─► Add to command history
+  └─► Show result feedback text (success/failure)
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnDebugCommandExecuted` | Command: FString | Command run |
+| `OnPanelChanged` | Panel: EDebugPanel | Switch panels |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) | Direct call | Execute commands |
+| [`BPC_FPSCounter`](../11-polish/79_BPC_FPSCounter.md) | Direct call | Performance data |
+| [`BPC_AIDirector`](../09-ai/57_BPC_AIDirector.md) | Direct call | AI debug state |
+| [`BPC_NarrativeState`](../07-narrative/36_BPC_NarrativeState.md) | Direct call | Story state |
+| [`BPC_DynamicEventSystem`](../10-adaptive/67_BPC_DynamicEventSystem.md) | Direct call | Event debug |
+| [`BPC_PlayerCamera`](../02-player/11_BPC_PlayerCamera.md) | Direct call | Camera modes |
+| [`BPC_DevCheatManager`](../11-polish/80_BPC_DevCheatManager.md) | Direct call | All cheat toggles |
+
+### Reuse Notes
+- Panel-based architecture allows easy addition of new debug panels
+- All interactive elements bound to DevCheatManager functions
+- Comms-visible only; all logic lives in DevCheatManager
+- Command input field mirrors console functionality
+- Quick-nav keyboard shortcuts for common panels
+- Compact/minimized mode for minimal screen intrusion during gameplay
+- Designed for developer productivity, not end users
--- a/docs/blueprints/13-polish/114_WBP_SplashScreen.md
+++ b/docs/blueprints/13-polish/114_WBP_SplashScreen.md
@@ -0,0 +1,157 @@
+# 78 — WBP_SplashScreen
+
+## Blueprint Spec — UE 5.5–5.7
+
+---
+
+### Parent Class
+`UserWidget`
+
+### Dependencies
+- [`BPC_LoadingScreen`](../11-polish/76_BPC_LoadingScreen.md) — Transition to loading
+- [`BPC_AudioManager`](../10-adaptive/66_BPC_AudioManager.md) — Splash audio
+- [`BPC_InputManager`](../02-player/13_BPC_InputManager.md) — Skip input
+- [`GI_GameManager`](../01-core/05_GI_GameManager.md) — Boot flow control (Phase 0)
+- [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) — Check for existing save
+
+### Purpose
+Introductory splash screen sequence shown on game boot before the main menu or loading screen. Displays company logos, game title, engine badges, and legal notices in a timed sequential presentation. Supports skip-to-main-menu via input, accessibility features (slow mode), and conditional branching based on save state.
+
+### Enums
+
+**ESplashElementType**
+
+| Value | Description |
+|-------|-------------|
+| CompanyLogo | Developer/publisher logo |
+| EngineLogo | UE5 logo, power badges |
+| GameTitle | Full game title card |
+| LegalNotice | Copyright, ratings info |
+| Warning | Health/safety warnings |
+| AccessibilityNotice | Accessibility info |
+
+### Structs
+
+**FSplashElement**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| ElementType | ESplashElementType | What to show |
+| DisplayDuration | Float | Seconds to display |
+| FadeInTime | Float | Fade in duration |
+| FadeOutTime | Float | Fade out duration |
+| Texture | UTexture2D | Logo/image to show |
+| TitleText | FText | Optional text overlay |
+| SubtitleText | FText | Optional subtitle |
+| bCanSkip | Bool | Allow skip this element |
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `SplashSequence` | TArray\<FSplashElement\> | Ordered splash elements |
+| `CurrentElementIndex` | Int32 | Active element |
+| `bIsPlaying` | Bool | Sequence running |
+| `bSkipped` | Bool | User skipped |
+| `bSlowMode` | Bool | Accessibility slow mode |
+| `CurrentTimer` | Float | Element timer |
+| `bTransitionComplete` | Bool | Sequence done |
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `PlaySplashSequence` | — | — | Start boot splash |
+| `ShowElement` | Element: FSplashElement | — | Display single element |
+| `AdvanceToNext` | — | — | Move to next element |
+| `SkipSplash` | — | — | End sequence early |
+| `FadeInElement` | Duration: Float | — | Fade animation |
+| `FadeOutElement` | Duration: Float | — | Fade animation |
+| `HandleInput` | Action: FName | — | Skip/confirm binding |
+| `OnSequenceComplete` | — | — | Splash finished |
+| `SetSlowMode` | bEnabled: Bool | — | Accessibility mode |
+| `CheckSaveState` | — | Bool | Has existing save |
+
+### Blueprint Flow
+
+```
+[PlaySplashSequence]
+  └─► Create splash sequence from configuration:
+         CompanyLogo (3s display, 1s fade in/out)
+         EngineLogo (2s display, 0.5s fade in/out)
+         GameTitle (4s display, 1.5s fade in/out)
+         LegalNotice (3s display, 1s fade in/out)
+  └─► bIsPlaying = true
+  └─► CurrentElementIndex = 0
+  └─► ShowElement(SplashSequence[0])
+  └─► Bind input actions:
+         BPC_InputManager -> "Confirm" -> SkipSplash()
+         BPC_InputManager -> "Pause" -> SkipSplash()
+
+[ShowElement]
+  └─► Get Element = SplashSequence[CurrentElementIndex]
+  └─► Set visibility for appropriate canvas panel
+  └─► If Element.Type == CompanyLogo:
+         Set logo image, center
+  └─► Else if Element.Type == GameTitle:
+         Set title text, subtitle, large text block
+  └─► Else if Element.Type == LegalNotice:
+         Set legal text, small, bottom-aligned
+  └─► Play FadeInElement(Element.FadeInTime)
+  └─► Timer = 0
+  └─► Tick:
+         Timer += DeltaTime
+         If Timer >= Element.DisplayDuration:
+              AdvanceToNext()
+
+[AdvanceToNext]
+  └─► Play FadeOutElement(CurrentElement.FadeOutTime)
+  └─► On fade complete:
+         Hide current element
+         CurrentElementIndex++
+         If CurrentElementIndex >= SplashSequence.Length:
+              OnSequenceComplete()
+         Else:
+              ShowElement(SplashSequence[CurrentElementIndex])
+
+[SkipSplash]
+  └─► If bSkipped: return
+  └─► bSkipped = true
+  └─► Fade out current element (fast, 0.2 seconds)
+  └─► Clear all elements
+  └─► OnSequenceComplete()
+
+[OnSequenceComplete]
+  └─► bIsPlaying = false
+  └─► CheckSaveState():
+         If save exists: Load main menu
+         If no save: Show main menu (new game focus)
+         If first boot ever: Show language/accessibility prompt
+  └─► Broadcast OnSplashComplete()
+  └─► Remove self from viewport
+```
+
+### Event Dispatchers
+
+| Name | Payload | Description |
+|------|---------|-------------|
+| `OnSplashComplete` | bSkipped: Bool | Splash sequence done |
+
+### Communications With
+
+| Target | Method | Why |
+|--------|--------|-----|
+| [`BPC_LoadingScreen`](../11-polish/76_BPC_LoadingScreen.md) | Direct call | Load main menu |
+| [`BPC_AudioManager`](../10-adaptive/66_BPC_AudioManager.md) | Direct call | Splash audio |
+| [`BPC_InputManager`](../02-player/13_BPC_InputManager.md) | Event binding | Skip input |
+| [`GI_GameManager`](../01-core/05_GI_GameManager.md) | Direct call | Boot flow |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Direct call | Save detection |
+
+### Reuse Notes
+- Fully configurable splash sequence via data
+- Supports accessibility slow mode (doubles all durations)
+- Skip input at any point
+- First-boot branching for language/accessibility setup
+- Handles both new game and existing save flows
+- Legal notice compliance baked into sequence
+- Can be reused for "press any key" or demo mode splash screens