HUD & UI Implementation Plan

Problem, Scope & Execution Boundary

UI ปัจจุบันเป็น UMG widgets ที่ถูกเปิดโดย GameInstance subsystems แยกกันและยังไม่มี screen stack กลาง ขณะที่ target design ต้องรองรับ menu navigation, modal priority, controller focus, dynamic glyphs, multiplayer input blocking, SP pause, localization และทุกระบบที่ยังพัฒนาไม่ครบ แผนนี้จึงสร้าง foundation ก่อน แล้วค่อยย้าย screen แบบ vertical slices โดยไม่ตัดระบบเดิมพร้อมกันทั้งหมด

Verified Current Implementation vs Target

Gate G0 Baseline & Review Evidence

Decision and evidence register

Verified legacy asset-reference snapshot

Config snapshot: DefaultGame.ini points HUD and inventory soft classes to WBP_HUD and WBP_Inventory. Lambeer.Build.cs includes UMG/Slate/SlateCore but not CommonUI/CommonInput, and Lambeer.uproject does not enable CommonUI. Xbox and PlayStation glyph assets exist under /Game/Lambeer/UI/ControllerGlyphs/.

Frozen migration/rollback strategy — owner approved 2026-09-06

1. Make a source-control checkpoint limited to the verified HUD/UI source, config, and seven legacy widget assets; do not mix unrelated dirty assets into the migration checkpoint.
2. Create the CommonUI root and new screens alongside legacy paths. Do not rename, move, delete, or redirect WBP_HUD, WBP_Inventory, or WBP_InteractionPrompt during G1–G2.
3. Switch through the existing soft-class config/facade seam only after the new root compiles and a missing-class path fails explicitly.
4. Before each legacy removal, repeat Asset Registry dependency/referencer capture, fix config/C++ fallback paths, run redirector validation, compile Editor/Game/Server, and complete cook/package smoke.
5. Rollback by restoring the legacy soft-class config and compatibility facades; remove redirectors only after the matching user PIE regression result is recorded.

User-supplied PIE baseline evidence

Unreal MCP log corroboration: user-run New Editor Window PIE started on /Game/Lambeer/World/Maps/L_Dev_Sandbox/L_Dev_Sandbox at 20:12 and 20:13 local time with one dedicated-server world and two client worlds. The logs prove session topology/start/teardown only, not visual or interaction correctness.

Reviewed user-only baseline acceptance matrix

Target Architecture [CONFIRMED 2026-09-06]

Owner approved. The Hybrid CommonUI + UMG architecture, one root per local player, four-layer ownership model, compatibility-facade migration, and SP/MP input-state policy below are frozen for G1 implementation.

ULambeerUIManagerSubsystem : ULocalPlayerSubsystem
└─ WBP_UIRoot : ULambeerUIRootWidget / UCommonUserWidget
   ├─ Layer_GameHUD : Overlay                         // passive UMG
   │  ├─ WBP_HUDRoot : ULambeerHUDWidget
   │  ├─ WBP_ContextStatusList
   │  ├─ WBP_NotificationFeed
   │  └─ WBP_InteractionPromptHost
   ├─ Layer_Screens : UCommonActivatableWidgetStack  // one primary screen
   ├─ Layer_Modals  : UCommonActivatableWidgetStack  // context/split/errors
   └─ Layer_Toast   : WBP_ToastQueue                 // non-blocking notices

Gameplay components replicate canonical state.
UI manager owns only local presentation, activation, focus, safe-zone and device state.
Every server mutation is requested through the owning gameplay component/service and re-rendered from accepted state.

C++ ownership rules

• ULambeerUIManagerSubsystem is the only layer/router owner per local player.
• ULambeerActivatableWidget centralizes CommonUI input config, back behavior, initial focus and restoration.
• Passive widgets remain UUserWidget; screens/modals derive from CommonUI activatable bases.
• Presentation structs are local read models, not new replicated gameplay databases.
• Widgets subscribe in construct/activate and unsubscribe in destruct/deactivate; no gameplay polling on Tick unless a specific visual interpolation needs it.
• Blueprint owns layout/style and calls exposed C++ commands; authoritative logic remains in C++.

Input-state policy

Target Files, Assets & Migration Map

Paths marked Proposed do not exist yet. Existing Blueprint assets must be edited by the user.

Source/Lambeer/UI/
├─ Common/                                      [Proposed]
│  ├─ LambeerUIManagerSubsystem.h/.cpp
│  ├─ LambeerUIRootWidget.h/.cpp
│  ├─ LambeerActivatableWidget.h/.cpp
│  ├─ LambeerUIActionTypes.h
│  └─ LambeerUITypes.h
├─ HUD/                                         [Proposed organization]
│  ├─ LambeerHUDWidget.*                        [move only in planned migration]
│  ├─ LambeerStatusBarsWidget.*
│  ├─ LambeerCompassWidget.*
│  ├─ LambeerInteractionPromptWidget.*
│  └─ LambeerScreenEffectsWidget.*
├─ Screens/                                     [Proposed]
│  ├─ LambeerInventoryWidget.*                  [derive activatable]
│  ├─ LambeerMapScreen.* / LambeerSpawnScreen.*
│  ├─ LambeerCraftingScreen.* / LambeerWorkbenchScreen.*
│  ├─ LambeerSettingsScreen.* / LambeerPauseScreen.*
│  └─ LambeerServerBrowserScreen.* / LambeerGroupScreen.*
└─ Legacy/                                      [optional transitional namespace, no asset move]

Content/Lambeer/UI/
├─ Common/Styles/  DA_UITheme, CommonButton/Text styles        [Proposed]
├─ Common/Icons/   T_UI_* imported from RawResource/UI/Icons/  [Proposed]
├─ Common/Input/   CommonInput controller data + action data    [Proposed]
├─ HUD/            WBP_UIRoot, WBP_HUDRoot, HUD child widgets   [Proposed + existing migration]
├─ Menus/          Main/Save/Server/Character/Spawn/Pause       [Proposed]
├─ Inventory/      existing assets + context/transfer screens   [Mixed]
├─ Map/, Crafting/, Building/, Weapons/, Social/, Settings/     [Proposed]
└─ ControllerGlyphs/                                             [Verified existing; preserve]

Config: Lambeer.uproject, Lambeer.Build.cs, DefaultEngine.ini, DefaultGame.ini
Input: Content/Lambeer/Core/Input/Actions/ and IMC_Default

Data Model, Interfaces & Events

ชื่อด้านล่างเป็น target contract จาก feature spec; implementation must first search for an existing gameplay-owned equivalent and reuse it where semantics match.

Required event surface

OnHUDSnapshotChanged(const FUIHUDSnapshot&)
OnInteractionPromptChanged(const FInteractionPromptState&)
OnObservedWeaponInfoChanged(ELambeerHeldHand, const FUIWeaponHandState&)
OnMapMarkersChanged(const TArray<FUIMapMarker>&)
OnCraftQueueChanged(FGuid QueueId)
OnAchievementUnlocked(FName AchievementId, const FRewardPayload&)
OnGroupActivityLogged(const FGroupActivityLogEntry&)
OnInputMethodChanged(ECommonInputType, FName GamepadName)

Error contract

• Every asynchronous screen has Loading, Ready, Empty, Error and Stale/Retry states where applicable.
• Rejected server action returns a localizable reason code; widgets do not parse arbitrary server strings.
• Missing optional backend displays unavailable state and logs once; it must not crash or fabricate data.
• Top modal receives errors that block the current operation; non-blocking results use toast.

Ordered Milestone Gates

ไม่มี calendar dates ตาม roadmap หลัก แต่ละ gate ต้องผ่าน exit criteria ก่อนเปิดงานที่พึ่งพา gate ถัดไป งาน screen ที่ไม่พึ่ง backend สามารถทำ visual shell ล่วงหน้าได้โดยแสดง unavailable/preview state เท่านั้น

Detailed Task Register

No tasks match the current filters.

Screen-to-Task Coverage Crosswalk

Screen IDs และหน้าที่เป็น canonical ใน FEAT-HUD-UI; ตารางนี้ชี้เฉพาะ implementation owner task และ gate เพื่อไม่ทำซ้ำ behavior specification

Replication, Persistence & Security Rules

• UI RPC requests carry stable IDs and expected version/revision where stale-selection risk exists; never trust client index alone.
• Server rejection must trigger refresh from authoritative state and show a localizable reason.
• Owner-only/private data is not replicated to unrelated players merely to simplify UI.
• Death marker lifetime follows loot-bag entity state; it is not a separate permanent client marker.
• Achievement unlock is idempotent; toast appears only after durable/authoritative acceptance.
• Crafting reserve/refund must be transaction-safe against reconnect, retry and station destruction.

Performance & Failure Handling

ไม่มี numeric performance budget ที่อนุมัติ จึงใช้ structural rules และวัดจริงโดยไม่ตั้งตัวเลขเป้าหมายเอง

Verification Strategy & Required Evidence

Automated/non-interactive checks

• Editor/Game/Server C++ compile after each C++ gate.
• Pure C++ automation tests for deterministic contracts and server validation boundaries.
• Asset path/config validation for root, screen registry, input data, fonts and icons.
• Repository search proving forbidden hit/headshot/kill marker APIs and bindings are absent.
• Localization gather/report shows no unkeyed player-facing strings in the changed scope.
• Cook/package smoke detects editor-only or missing soft references.

User-only Unreal Editor checks

• Compile/save each Widget Blueprint after C++ parent change; resolve BindWidget names.
• Run PIE checklist from PIE-UI-001…012.
• Record resolution/aspect, language, device, SP/MP mode, result and evidence.
• Only mark a gate verified after user-reported results are captured; agent must not infer a PIE pass.

Regression matrix

Definition of Done per Screen

• Screen ID and class/asset path match FEAT-HUD-UI; proposed asset is verified after creation.
• All authoritative commands route through C++ service/component and handle rejection.
• Loading/empty/error/denied states are designed where applicable.
• Mouse, keyboard, Xbox and PlayStation navigation work; focus has a visible state and no trap.
• English and Thai copy comes from localizable text; no clipping at supported scale/aspect.
• Semantic state is conveyed by icon/shape/text as well as color.
• Delegates are removed on deactivation/destruction; latent loads/callbacks cannot update a dead screen.
• Automated checks pass where applicable; user-run PIE evidence is recorded.
• Related canonical HTML docs are updated when implementation changes the contract.
• Legacy asset/code is removed only after redirect/cook/regression gates pass.

Technical Decisions / Blocking TBDs

Dependencies & Source of Truth

Plan source of truth: เอกสารนี้กำหนด implementation order, file impacts, gates และ verification evidence ส่วนพฤติกรรม player-facing ยังคง canonical ใน FEAT-HUD-UI และ gameplay authority/value อยู่ใน feature/technical docs ของระบบนั้น