Project: UI architecture — three-layer stable pattern

Agreed 2026-04-24. Read once per session. Full design: docs/plans/2026-04-24-ui-framework.md.

The separation

┌─────────────────────────────────────────┐
│  UI backend (ImGui today / custom later)│  ← swappable
├─────────────────────────────────────────┤
│  ViewModels + Commands (per-panel)      │  ← stable contracts
├─────────────────────────────────────────┤
│  Game state + events + net (unchanged)  │  ← game logic
└─────────────────────────────────────────┘

UI backend (bottom swap axis): ImGui.NET + Silk.NET.OpenGL.Extensions.ImGui for Phase D.2a (short-term, debugger-look, validates game logic fast). Custom retail-look toolkit for Phase D.2b (long-term, uses dat assets). ImGui stays forever as the ACDREAM_DEVTOOLS=1 overlay. (Pivoted from Hexa.NET.ImGui on 2026-04-25 — Hexa's native OpenGL3 backend resolves GL via GLFW/SDL internally and crashed 0xC0000005 against Silk.NET; the Silk.NET extension is purpose-built for this stack.)
ViewModels + Commands (the stable contract): per-panel data records (VitalsVM, InventoryVM, ChatVM, …) and action records (UseItemCmd, SendChatCmd, CastSpellCmd, …). Lives in AcDream.UI.Abstractions. Does not change across the backend swap.
Game state + events + net: existing IGameState, IEvents, WorldSession, etc. Unchanged. UI only reads/subscribes; never touches these.

Module layout (future)

src/AcDream.UI.Abstractions/ — IPanel, IPanelHost, IPanelRenderer, ICommandBus, all ViewModels + Commands. Backend- agnostic.
src/AcDream.UI.ImGui/ — ImGui.NET + Silk.NET.OpenGL.Extensions.ImGui implementation of IPanelRenderer + ImGui bootstrap. Phase D.2a. ImGuiController (from the Silk.NET extension) handles GL backend + input event subscription; ImGuiBootstrapper is a thin IDisposable wrapper; ImGuiPanelRenderer wraps the widgets IPanelRenderer needs.
src/AcDream.UI.Retail/ (later) — custom retained-mode toolkit using dat assets, same IPanelRenderer contract. Phase D.2b.

Hard rules

No panel references a backend namespace. If a panel imports ImGuiNET / Silk.NET.OpenGL.Extensions.ImGui or a custom-toolkit widget class directly, it's a bug — extend IPanelRenderer instead.
Plugin API targets the abstraction layer only. Plugins define IPanel instances; they never see which backend draws them.
Features that only ImGui can express → not in IPanelRenderer. If a feature can't be expressed by a future retained-mode toolkit with dat-sourced sprites/fonts, don't expose it in the abstraction.
D.3 AcFont / D.4 dat sprites / D.7 cursor manager are D.2b dependencies — they plug into the custom backend only.
D.5 core panels / D.6 HUD ship against the abstraction, not against a specific backend. They render via ImGui first, reskin under custom later.

Why staged (not pure custom from day one)

Gets the whole game-logic loop validated in weeks: chat-send, inventory-click, vitals-bar-read-from-real-state. Requires zero widget art.
Forces the abstraction design to pass a real backend test before we commit to the custom toolkit. If IPanelRenderer is wrong, we discover it during Phase D.2a, not after Phase D.2b lands with a dozen broken panels.
Custom retail-look toolkit then delivers the aesthetic layer without the plugin API or game logic needing to change.

2026-07-10 retained radar update

The older "D.6 ships through IPanelRenderer/ImGui first" rule above is superseded for screen-space retail HUD windows. The production retained toolkit now lives in src/AcDream.App/UI; imported LayoutDesc windows bind through dedicated gm*UI controllers and App-layer snapshot providers. ImGui remains devtools only.

gmRadarUI is the reference pattern: Core owns exact colors/shapes/projection/ compass/coordinates, RadarSnapshotProvider joins the existing WorldEntity + ClientObjectTable two-table model, RadarController binds LayoutDesc 0x21000074, and UiRadar only draws/handles retained interaction. GameWindow contains mount and delegate wiring, not the feature body. See docs/research/2026-07-10-retail-radar-pseudocode.md.

2026-07-10 retained window ownership

Every production retained window is registered through RetailWindowManager and owned by a typed RetailWindowHandle. Controllers implement IRetainedPanelController; windows with multiple focused controllers use RetainedPanelControllerGroup, which forwards lifecycle in construction order and disposes in reverse order exactly once. A controller created after a hidden mount (inventory) is attached through RetailWindowManager.AttachController.

Controller event subscriptions must use removable named handlers or paired subscribe/unsubscribe delegates. UiHost.Dispose first removes Silk mouse/keyboard subscriptions, then disposes the manager/controllers, then the GL text renderer. GameWindow.OnClosing disposes layout persistence and UiHost before live session or game-state sources. This ordering is the recreate/relogin double-subscription guard; do not reintroduce anonymous lifetime-bound event lambdas.

2026-07-11 composition boundary

RetailUiRuntime now owns production retained composition. Its focused binding records receive state/action delegates plus DAT/font/sprite resolvers; GameWindow.OnLoad retains only resolver/service creation and one declarative RetailUiRuntime.Mount call. All LayoutDesc imports, controller construction, window mounts, toolbar digit and inventory-cell asset lookup, plugin mounts, cursor feedback, persistence, automation, and retained tick/draw/restore/dispose paths live behind the runtime. The live Debug gate passed across two graceful restart cycles. Do not add panel mount bodies back to GameWindow.

6.5 KiB Raw Blame History