admin/UE5-Modular-Game-Framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
UE5-Modular-Game-Framework/docs/architecture/hud-overview.md
admin 7e34765e61 add architecture
2026-05-19 10:16:14 +00:00

7.9 KiB
Raw Permalink Blame History

HUD System Architecture — Modular Game Framework

Architecture Overview | UE 5.5–5.7 | Widget Blueprint

This document explains how the 14 UI widgets in docs/blueprints/06-ui/ connect and interact. Use this as a wiring reference when implementing the HUD layer.

Widget Hierarchy

flowchart TD
    WBP_HUDController[WBP_HUDController — Root HUD Container] --> Diegetic[WBP_DiegeticHUDFrame — Health, Stress, Stamina, Compass]
    WBP_HUDController --> Prompt[WBP_InteractionPromptDisplay — Interaction cues]
    WBP_HUDController --> Subtitle[WBP_AccessibilityUI — Subtitles, Accessibility overlays]
    WBP_HUDController --> Toast[WBP_NotificationToast — Toast messages]
    WBP_HUDController --> Objective[WBP_ObjectiveDisplay — Active objectives]
    WBP_HUDController --> ScreenFX[WBP_ScreenEffectController — Damage, Stress, Flash]
    
    SS_UIManager[SS_UIManager — Menu Stack Manager] --> MainMenu[WBP_MainMenu]
    SS_UIManager --> PauseMenu[WBP_PauseMenu]
    SS_UIManager --> Inventory[WBP_InventoryMenu]
    SS_UIManager --> Journal[WBP_JournalDocumentViewer]
    SS_UIManager --> Settings[WBP_SettingsMenu]
    SS_UIManager --> MenuFlow[WBP_MenuFlowController — State Machine]
    
    SS_UIManager -.->|Input Mode Sync| SS_EnhancedInputManager
    SS_UIManager -.->|Visibility| WBP_HUDController

Two-Layer Architecture

Layer Manager Widgets When Visible
HUD Layer WBP_HUDController 45-48, 53-54, 56 Gameplay only
Menu Layer SS_UIManager (44) 49-52, 55, 57 On top of gameplay (pause, menu, inventory)

Rule: WBP_HUDController hides when any full-screen menu opens. SS_UIManager handles the menu stack (push/pop). Only one layer is interactive at a time.

Widget Quick Reference

# Widget Lines Role Key Input Key Output
44 SS_UIManager — Menu stack subsystem PushMenu/PopMenu Input mode, cursor state
45 WBP_AccessibilityUI 141 Subtitles + accessibility OnDialogueLine dispatcher Subtitle text on screen
46 WBP_DiegeticHUDFrame 89 In-world HUD skin Player state dispatchers Health/stress/stamina display
47 WBP_HUDController 114 Root HUD container Game phase changes Child widget visibility
48 WBP_InteractionPromptDisplay 135 Interaction cues OnFocusGained/OnFocusLost Prompt text + progress ring
49 WBP_InventoryMenu — Inventory grid UI BPC_InventorySystem data Drag-drop, equip, drop
50 WBP_JournalDocumentViewer — Document/journal reader BPC_DocumentArchiveSystem Paged text with font styles
51 WBP_MainMenu — Main menu screen Game start/load events New game, continue, settings
52 WBP_MenuFlowController — Menu state machine Menu transitions Back navigation
53 WBP_NotificationToast 52 Toast notifications Any system dispatcher Slide-in text + icon
54 WBP_ObjectiveDisplay 86 Objective overlay BPC_ObjectiveSystem events Objective text + progress
55 WBP_PauseMenu — Pause menu Pause input action Resume, save, load, quit
56 WBP_ScreenEffectController 43 Full-screen effects Health/stress events Damage vignette, flash
57 WBP_SettingsMenu — Settings screen SS_SettingsSystem Audio/video/controls tabs

Data Flow: HUD Widgets

Player State Components          HUD Layer
┌─────────────────────┐          ┌──────────────────────────┐
│ BPC_HealthSystem     │─OnHealthChanged──→│ WBP_DiegeticHUDFrame     │
│ BPC_StressSystem     │─OnStressTierChanged→│ WBP_ScreenEffectController│
│ BPC_StaminaSystem    │─OnStaminaChanged─→│ (via WBP_HUDController)  │
│ BPC_InteractionDetector│─OnFocusGained───→│ WBP_InteractionPromptDisplay│
│ BPC_DialoguePlayback │─OnDialogueLine───→│ WBP_AccessibilityUI      │
│ BPC_ObjectiveSystem  │─OnObjectiveUpdate→│ WBP_ObjectiveDisplay     │
│ Any System           │─ShowToast───────→│ WBP_NotificationToast    │
└─────────────────────┘          └──────────────────────────┘

Key: WBP_ widgets NEVER write to game state. They only read via dispatchers.

Data Flow: Menu Widgets

Input Event                    Menu Layer (SS_UIManager)
┌──────────────────┐           ┌─────────────────────────┐
│ IA_Pause          │──→       │ PushMenu(PauseMenu)      │
│ IA_Inventory      │──→       │ PushMenu(InventoryMenu)  │
│ IA_Journal        │──→       │ PushMenu(JournalViewer)  │
│ IA_Escape (back)  │──→       │ PopMenu() — back nav     │
│                   │           │                         │
│ WBP_SettingsMenu  │──SetFloat→│ SS_SettingsSystem        │
│                   │           │  └→ SS_AudioManager.SetBusVolume│
│                   │           │  └→ Save to persistent storage│
└──────────────────┘           └─────────────────────────┘

Implementation Order (Dependency-Safe)

Step Widget Depends On Reason
1 WBP_HUDController (47) (none) Root container — must exist first
2 WBP_DiegeticHUDFrame (46) 47 Parented by HUDController
3 WBP_InteractionPromptDisplay (48) 47, BPC_InteractionDetector (16) Needs prompt data
4 WBP_NotificationToast (53) 47 Parented by HUDController
5 WBP_ObjectiveDisplay (54) 47, BPC_ObjectiveSystem (59) Needs objective data
6 WBP_ScreenEffectController (56) 47 Parented by HUDController
7 WBP_AccessibilityUI (45) 47, BPC_DialoguePlaybackSystem (60) Needs dialogue events
8 SS_UIManager (44) (none — subsystem) Menu stack manager
9 WBP_MenuFlowController (52) 44 Menu state machine
10 WBP_MainMenu (51) 44, 52 First menu pushed
11 WBP_PauseMenu (55) 44, 52 Push on pause
12 WBP_SettingsMenu (57) 44, 52, SS_SettingsSystem (105) Push from menus
13 WBP_InventoryMenu (49) 44, BPC_InventorySystem (31) Needs inventory data
14 WBP_JournalDocumentViewer (50) 44, BPC_DocumentArchiveSystem (29) Needs document data

Key Integration Points with New Systems (130-135)

Widget Integration
WBP_HUDController Reads BPC_StateManager (130).OnStateChanged — hides HUD during InCutscene, InMainMenu, Loading
WBP_InteractionPromptDisplay Calls BPC_StateManager.IsActionPermitted(ActionTag) — shows "Blocked: [Reason]" when action denied
WBP_InteractionPromptDisplay Reads BPC_StateManager.OnStateChangeDenied — displays BlockReason to player
WBP_SettingsMenu Calls SS_AudioManager (132).SetBusVolume() for each volume slider
WBP_SettingsMenu Calls SS_AudioManager.GetBusVolume() to populate slider defaults
WBP_AccessibilityUI Reads BPC_StateManager.GetHeartRate() for visual heartbeat indicator (deaf accessibility)
WBP_DiegeticHUDFrame Reads BPC_StateManager.GetVitalSignal() to show heart rate tier indicator

Architecture Overview: HUD System. See 44_SS_UIManager.md for the menu stack subsystem spec. See 47_WBP_HUDController.md for the root HUD container spec.