add blueprints

docs/blueprints/06-ui/52_WBP_MenuFlowController.md

@@ -0,0 +1,83 @@
+# WBP_MenuFlowController — Widget (Menu Flow Controller)
+
+**Parent:** `UUserWidget` (non-visible overlay that lives under SS_UIManager)
+**Depends On:** `SS_UIManager`, `GI_GameFramework`, `SS_SaveManager`
+
+---
+
+### Purpose
+Orchestrates transitions between MenuFlow states: SplashScreen > MainMenu > Settings transitions > Loading transitions > Level transitions > Credits > Quit.
+
+### Variables
+
+| Name | Type | Description |
+|------|------|-------------|
+| `CurrentFlowState` | `E_MenuFlowState` | Current flow state |
+| `FadeWidget` | `Image` | Black full-screen fade image |
+| `FadeDuration` | Float | Fade duration in seconds (1.0) |
+| `AnimFadeIn` | `WidgetAnimation` | Fade from 0 to 1 opacity |
+| `AnimFadeOut` | `WidgetAnimation` | Fade from 1 to 0 opacity |
+| `bIsTransitioning` | Bool | Block input during transition |
+
+### Enums
+
+```cpp
+E_MenuFlowState
+{
+    SplashScreen,
+    MainMenu,
+    Settings,
+    Loading,
+    InGame,
+    Paused,
+    Credits,
+    Quit
+}
+```
+
+### Functions
+
+| Name | Inputs | Outputs | Description |
+|------|--------|---------|-------------|
+| `TransitionToState` | NewState: `E_MenuFlowState` | — | Fade out, switch state, fade in |
+| `OnSplashComplete` | — | — | Auto-transition to MainMenu after splash timer |
+| `OnFadeOutComplete` | — | — | Switch visibility, load levels, then fade in |
+| `OpenMainMenu` | — | — | OpenLevel "MainMenu", then TransitionToState MainMenu |
+| `StartNewGame` | — | — | Fade out, OpenLevel first level, set InGame |
+| `ReturnToMainMenu` | — | — | OpenLevel "MainMenu", TransitionToState MainMenu |
+| `ShowCredits` | — | — | OpenLevel "CreditsMap", TransitionToState Credits |
+| `IsTransitioning` | — | Bool | Query lock |
+
+### Blueprint Flow — Menu Flow Transitions
+
+```mermaid
+flowchart LR
+    A[Splash] -->|timer| B[MainMenu]
+    B -->|New Game| C[Fade Out]
+    C --> D[OpenLevel FirstLevel]
+    D --> E[Fade In]
+    E --> F[InGame]
+    B -->|Settings| G[Push Settings Menu]
+    G -->|Back| B
+    F -->|ESC| H[Push Pause Menu]
+    H -->|Resume| F
+    H -->|Quit to Menu| I[Fade Out]
+    I --> J[OpenLevel MainMenu]
+    J --> B
+    F -->|Death| K[Fade to Black]
+    K --> L[Respawn or AltDeathSpace]
+    F -->|Credits| M[OpenLevel Credits]
+```
+
+### Communications With
+
+| Target System | Method | Why |
+|--------------|--------|-----|
+| [`SS_UIManager`](44_SS_UIManager.md) | Push/Pop/Close/Open | Menu lifecycle |
+| [`GI_GameFramework`](../01-core/04_GI_GameFramework.md) | SetGamePhase, dispatchers | Phase transitions |
+| [`SS_SaveManager`](../05-saveload/28_SS_SaveManager.md) | Save/Load functions | Save slots |
+| [`WBP_HUDController`](WBP_HUDController.md) | Parent reference | Fade coordination |
+
+### Reuse Notes
+- Manages transitions centrally — no individual menu needs to open levels or handle fade logic
+- Split from original bundled `36_WBP_MenuWidgets.md` per Clean Slate refactoring plan