From ba346d9fe6064fa59d94c684abe1ee11c9ca18b1 Mon Sep 17 00:00:00 2001 From: admin Date: Tue, 19 May 2026 11:11:03 +0000 Subject: [PATCH] Add UI, Menus & Diegetic Presentation Systems --- ...Menus-%26-Diegetic-Presentation-Systems.md | 157 ++++++++++++++++++ 1 file changed, 157 insertions(+) create mode 100644 UI%2C-Menus-%26-Diegetic-Presentation-Systems.md diff --git a/UI%2C-Menus-%26-Diegetic-Presentation-Systems.md b/UI%2C-Menus-%26-Diegetic-Presentation-Systems.md new file mode 100644 index 0000000..d341c7b --- /dev/null +++ b/UI%2C-Menus-%26-Diegetic-Presentation-Systems.md @@ -0,0 +1,157 @@ +# 06 — UI, Menus & Diegetic Presentation Systems (Systems 44-57) + +**Category Purpose:** These 14 systems form the complete UI layer — menu management, HUD presentation, inventory display, interaction prompts, notifications, screen effects, settings, accessibility, and diegetic in-world interfaces. The `SS_UIManager` is the central orchestrator; all widgets operate under its stack-based menu system. The architectural principle "UI Reads, Never Writes" applies: widgets display data but never own game logic. + +--- + +## System Index + +| # | System | Asset Type | Role | +|---|--------|-----------|------| +| 44 | `SS_UIManager` | Subsystem | UI subsystem; menu stack, context-based switching, input mode | +| 45 | `WBP_AccessibilityUI` | Widget | Accessibility settings; subtitles, colorblind, controller | +| 46 | `WBP_DiegeticHUDFrame` | Widget | Diegetic in-world HUD frame (wristwatch, helmet display) | +| 47 | `WBP_HUDController` | Widget | Root HUD widget; manages all HUD sub-widgets | +| 48 | `WBP_InteractionPromptDisplay` | Widget | Interaction prompt popup; key, description, hold progress | +| 49 | `WBP_InventoryMenu` | Widget | Inventory grid UI; drag-drop, sort, examine, equip, drop | +| 50 | `WBP_JournalDocumentViewer` | Widget | Document/journal viewer; pages, font styles, highlights | +| 51 | `WBP_MainMenu` | Widget | Main menu; new game, continue, load, settings, quit | +| 52 | `WBP_MenuFlowController` | Widget | Menu state machine; transitions, back navigation | +| 53 | `WBP_NotificationToast` | Widget | Toast notification; objective update, item found, achievement | +| 54 | `WBP_ObjectiveDisplay` | Widget | Active objective HUD element; current quest/objective | +| 55 | `WBP_PauseMenu` | Widget | Pause menu; resume, settings, save, load, quit | +| 56 | `WBP_ScreenEffectController` | Widget | Full-screen effects; damage vignette, stress, flash | +| 57 | `WBP_SettingsMenu` | Widget | Settings menu; audio, video, controls, gameplay | + +--- + +## Architecture: UI Layer + +``` +┌────────────────────────────────────────────────────────────────┐ +│ UI ARCHITECTURE │ +│ │ +│ SS_UIManager (GameInstanceSubsystem) │ +│ │ Menu stack: push/pop menus with priority │ +│ │ Context switching: Default → Hiding → Wristwatch → UI │ +│ │ Input mode coordination with SS_EnhancedInputManager │ +│ │ │ +│ ├─► WBP_MenuFlowController (menu state machine) │ +│ │ ├─► WBP_MainMenu │ +│ │ ├─► WBP_PauseMenu │ +│ │ ├─► WBP_SettingsMenu → WBP_AccessibilityUI │ +│ │ └─► WBP_CreditsScreen │ +│ │ │ +│ └─► WBP_HUDController (ingame HUD root) │ +│ ├─► WBP_ObjectiveDisplay (current objective) │ +│ ├─► WBP_InteractionPromptDisplay (interact prompt) │ +│ ├─► WBP_NotificationToast (popup notifications) │ +│ ├─► WBP_ScreenEffectController (damage/stress FX) │ +│ ├─► WBP_DiegeticHUDFrame (in-world wristwatch) │ +│ └─► WBP_InventoryMenu (inventory screen) │ +│ └─► WBP_JournalDocumentViewer (documents) │ +└────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 44 — SS_UIManager: UI Orchestrator + +**What It Does:** The central UI authority. Manages a menu stack for push/pop navigation, handles context-based UI switching (Default/Hiding/Wristwatch/UI modes), coordinates input mode changes with `SS_EnhancedInputManager` (cursor visibility, input blocking), and provides the canonical entry point for opening any menu. + +**How It Works Internally:** + +**Menu Stack:** +- `PushMenu(MenuWidget)` — adds to stack, opens widget, applies input mode +- `PopMenu()` — removes top, returns to previous, restores input mode +- Priority-based: UI(100) > Inspection(20) > WristwatchUI(10) > Hiding(5) > Default(0) +- Higher priority menus block lower ones + +**Context Switching:** +- Listens to game state changes (death, hiding, combat) +- Automatically shows/hides appropriate HUD elements per context +- Coordinates with `SS_EnhancedInputManager` for input mode changes (game-only vs UI-only vs game-and-UI) + +**Input Mode Coordination:** +- On menu open: request UI input mode (show cursor, block game input) +- On menu close: request game input mode (hide cursor, enable game input) +- Handles edge cases: pause menu over inventory, settings over pause + +--- + +## 47 — WBP_HUDController: Root HUD Widget + +**What It Does:** The root widget that owns and manages all HUD sub-widgets. Handles visibility toggling based on game context, manages layout, and routes data from gameplay systems to correct sub-widgets. + +**Key Sub-Widgets Managed:** +- Health/stamina/stress bars (bound to respective system dispatchers) +- `WBP_ObjectiveDisplay` — current quest text +- `WBP_InteractionPromptDisplay` — shows/hides based on `OnTargetFound`/`OnTargetLost` +- `WBP_NotificationToast` — queued notification display +- `WBP_ScreenEffectController` — damage vignette, stress overlay +- `WBP_DiegeticHUDFrame` — wristwatch HUD for immersive mode + +**Data Flow:** HUD binds to dispatchers; never polls. `OnHealthChanged` → update health bar. `OnObjectiveTagsChanged` → update objective text. `OnTargetFound` → show interaction prompt. + +--- + +## 48 — WBP_InteractionPromptDisplay: Interaction Prompt + +**What It Does:** Shows the "Press E to Open" style prompt when the player looks at an interactable. Handles three input modes: +- **Press:** shows key icon + action text +- **Hold:** shows radial fill progress bar + action text +- **DoubleTap:** shows double-tap indicator + +Binds to `BPC_InteractionDetector.OnTargetFound/Lost` and `OnHoldProgressUpdated`. + +--- + +## 49 — WBP_InventoryMenu: Inventory Grid UI + +**What It Does:** Full inventory screen with drag-and-drop grid layout. Displays all items from `BPC_InventorySystem`, supports sort modes, item inspection, equip/unequip, drop, use, and combine operations. + +**Features:** +- Grid-based layout with item icons and stack counts +- Drag-and-drop between slots (rearrange) +- Right-click context menu: Use, Equip, Drop, Examine, Combine +- Category tabs for filtering +- Weight bar showing current/max capacity +- Tooltip on hover showing item details (name, description, stats) +- Quick slot assignment (drag to hotbar) + +**Data Binding:** Subscribes to all `BPC_InventorySystem` event dispatchers. On any change, refreshes the affected slot, not the entire grid. + +--- + +## 51-57: Menu & Screen Widgets + +- **51 WBP_MainMenu:** New Game, Continue, Load Game, Settings, Quit. Checks save manifest for Continue availability. +- **52 WBP_MenuFlowController:** State machine for menu navigation. Handles transitions, back button, and prevents menu stacking bugs. +- **53 WBP_NotificationToast:** Animated popup for objectives, items, achievements. Queued system — multiple toasts stack vertically with auto-dismiss. +- **54 WBP_ObjectiveDisplay:** Shows current active objective text on HUD. Updates on `GS_CoreGameState.OnObjectiveTagsChanged`. +- **55 WBP_PauseMenu:** Resume, Settings, Save, Load, Quit to Menu. Checks `GM_CoreGameMode.bPauseAllowed`. +- **56 WBP_ScreenEffectController:** Full-screen post-process effects driven by gameplay state: damage vignette (red flash on hit), stress overlay (chromatic aberration, darkening), healing glow, death fade to black. +- **57 WBP_SettingsMenu:** Audio (volume sliders per bus), Video (resolution, quality), Controls (key rebinding via `SS_EnhancedInputManager`), Gameplay settings, Accessibility tab → `WBP_AccessibilityUI`. + +--- + +## 45-46, 50: Supporting Widgets + +- **45 WBP_AccessibilityUI:** Subtitle toggle/size, colorblind modes, controller remapping, difficulty presets, hold-to-confirm toggle. Reads/writes via `SS_SettingsSystem`. +- **46 WBP_DiegeticHUDFrame:** In-world HUD rendered on wristwatch or helmet display via `BPC_DiegeticDisplay`. Shows minimap, compass, health, ammo — diegetic (exists in world) not screen-space. +- **50 WBP_JournalDocumentViewer:** Reads documents from `BPC_DocumentArchiveSystem`. Page-turning interface with font styles, highlighted keywords, and categorization. + +--- + +## Common Implementation Patterns in This Category + +1. **UI Reads, Never Writes:** Widgets bind to gameplay dispatchers and display data. They call functions on systems (UseItem, EquipItem) but never own game state. +2. **Menu Stack Navigation:** `SS_UIManager.PushMenu()` / `PopMenu()` ensures clean navigation without manual visibility management. +3. **Context Priority Ladder:** Default(0) < Hiding(5) < WristwatchUI(10) < Inspection(20) < UI(100). Higher priority contexts override lower ones automatically. +4. **Input Mode Sync:** Every menu open/close coordinates with `SS_EnhancedInputManager` for cursor + input blocking. +5. **Dispatcher Binding, Not Polling:** All HUD widgets bind to gameplay dispatchers on construct and unbind on destruct. No widget uses Event Tick for polling. +6. **Toast Queue:** Notifications are queued and displayed sequentially with auto-dismiss — prevents notification spam. + +--- + +*Developer Reference v1.0 — 06 UI Systems. Companion to docs/blueprints/06-ui/ specs.*