UE5-Modular-Game-Framework/docs/developer/06-ui-systems.md

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.

---

Multiplayer Networking

All UI is local per-client. Zero networking code in widgets.

UI Networking Pattern

Server state changes → replicated variable → OnRep fires dispatcher
  → Widget (local) already bound to that dispatcher
  → Widget updates with zero multiplayer awareness

Category Rules

• WBP_ Widgets:* Local only. Bind to replicated dispatchers from gameplay systems. Use the same binding code as single-player.
• SS_UIManager: Local per-client. Menu stack is per-player — different players can be in different menus.
• Input mode changes: Handled per-client by SS_EnhancedInputManager listening to game phase dispatchers.
• HUD visibility: Each client independently determines what to show based on their replicated state (e.g., hiding player sees different HUD than exposed player).

---

Developer Reference v1.0 — 06 UI Systems. Companion to docs/blueprints/06-ui/ specs.