acdream/docs/plans/2026-04-24-ui-framework.md

# UI framework plan

**Date:** 2026-04-24 (design), shipped 2026-04-25
**Status:** **Phase D.2a shipped** — `AcDream.UI.Abstractions` + ImGui backend
+ `VitalsPanel` gated on `ACDREAM_DEVTOOLS=1`. Backend pivoted from
`Hexa.NET.ImGui` to `ImGui.NET` + `Silk.NET.OpenGL.Extensions.ImGui` during
first-light integration — see the pivot note below. Phase D.2b (custom
retail-look backend) remains design-only.
**Owner:** lead engineer (erik) + Claude

Captures the UI strategy agreed via discussion on 2026-04-24. Documents
the choices AND the alternatives considered so future sessions can
re-evaluate with the same context.

## 2026-04-25 pivot: Hexa.NET.ImGui → ImGui.NET

The original choice (documented below) was `Hexa.NET.ImGui` +
`Hexa.NET.ImGui.Backends.OpenGL3`. It did not survive first-light
integration:

- First launch with Hexa's backend crashed with `0xC0000005` inside
  `Hexa.NET.ImGui.Backends.OpenGL3.ImGuiImplOpenGL3.InitNative`.
- Root cause: Hexa's native OpenGL3 backend does its own GL function
  resolution, looking up symbols via GLFW or SDL. Silk.NET uses neither,
  so the resolved function pointers were null and the native code
  dereferenced them on init.
- Hexa's Silk.NET examples rely on GLFW being co-loaded (its default
  on Hexa's own scenes) — not applicable here.

**Mitigation path** was already written into this doc (§"What we give
up": *"switching to ImGui.NET later is a one-morning operation if Hexa
misbehaves"*) and taken:

- Packages swapped → `ImGui.NET 1.91.6.1` + `Silk.NET.OpenGL.Extensions.ImGui 2.23.0`.
- `Silk.NET.OpenGL.Extensions.ImGui.ImGuiController` handles the whole
  integration (GL backend init against the Silk.NET GL binding,
  keyboard + mouse IO event subscription). No hand-written input
  bridge needed.
- `ImGuiBootstrapper` is a ~10-line `IDisposable` wrapping the
  `ImGuiController` instance. `ImGuiPanelRenderer` wraps `ImGuiNET.ImGui.*`.
- Boundary discipline preserved — panels never import `ImGuiNET`
  directly; they only use `IPanelRenderer`. The backend swap is
  invisible above the abstraction layer, as designed.

Sections below from §"Choice: Hexa.NET.ImGui" onward are kept as the
historical design reasoning. They remain useful if we ever re-evaluate
native AOT / upstream-tracking tradeoffs.

## Goal

acdream needs a playable game UI: chat, vitals HUD, inventory, character
panel, skills, spellbook, fellowship, allegiance, trade, options, map,
quest log, tooltips — and a first-class plugin API so plugin authors can
ship their own panels.

## Strategy: two-phase, one stable interface

```
┌─────────────────────────────────────────┐
│  UI backend  ─  ImGui (short-term)      │  ← swappable
│              ─  Custom retail (later)   │
├─────────────────────────────────────────┤
│  ViewModels + Commands  (per panel)     │  ← stable contracts
├─────────────────────────────────────────┤
│  Game state + events + net (existing)   │  ← unchanged
└─────────────────────────────────────────┘
```

- **Near term:** wire an ImGui-based overlay so we can iterate on game
  logic fast — chat that actually sends + receives, inventory that
  reflects real state, vitals bar that reads real HP/stam/mana. Looks
  like a debugger, that's fine for now.
- **Later:** replace the visual layer with a custom toolkit that uses
  retail dat assets (icons, panels, fonts) and matches retail's feel.
- **Always:** ViewModels and Commands stay stable across the swap. The
  game logic never learns which backend is drawing it.

## Choice: Hexa.NET.ImGui for the short-term backend

Decision: **`Hexa.NET.ImGui`** + its bundled `Hexa.NET.ImGui.Backends.OpenGL3`.

### Why Hexa over ImGui.NET + Silk.NET.OpenGL.Extensions.ImGui

- **Auto-generated from cimgui, tracks upstream ImGui closely** — docking,
  viewports, tables current within days of release.
- **Native-AOT first-class** — single-file publish is painless; aligns
  with where we want acdream to land long-term for distribution.
- **Per-RID native-lib bundling** is cleaner — no separate `cimgui.dll`
  side-loading to manage.
- Ships its own Silk.NET-compatible OpenGL3 backend; the Silk.NET official
  extension is unnecessary.

### What we give up

- `Silk.NET.OpenGL.Extensions.ImGui` is battle-tested with hundreds of
  Silk.NET sample projects. Hexa's backend is newer, slightly higher risk
  of edge-case bugs.
- Mitigation: keep integration tight (~50 lines) so switching to
  ImGui.NET later is a one-morning operation if Hexa misbehaves.

### Why ImGui at all (vs. going straight to custom)

- Get game logic validated end-to-end in weeks, not months.
- ImGui stays forever as the **devtools layer** (`ACDREAM_DEVTOOLS=1`):
  packet trace inspector, state dump, dat browser. Having a working
  ImGui integration is a permanent asset even after game UI moves off it.
- Lets us design the **plugin API and ViewModel contracts against a
  real running panel** rather than designing in the abstract.

## The three layers in detail

### Layer 1 — Game state (unchanged)

Already exists: `IGameState`, `IEvents` (plugin-host interfaces),
`WorldSession`, `PlayerWeenie`, `Inventory`, `SpellBook`, `LightManager`,
the live-session wire code. The UI reads from these; we add nothing.

### Layer 2 — ViewModels + Commands

New module: `src/AcDream.UI.Abstractions/`. Backend-agnostic.

**ViewModels** — per-panel data contracts. Example:

```csharp
public sealed record VitalsVM(
    int   HpCurrent, int HpMax,
    int   StamCurrent, int StamMax,
    int   ManaCurrent, int ManaMax,
    float HpRegenRate,
    bool  Stunned,
    bool  LowHpWarning);

public sealed record InventoryVM(
    IReadOnlyList<InventoryItemVM> Items,
    int                            BurdenCurrent,
    int                            BurdenCapacity);

public sealed record ChatVM(
    IReadOnlyList<ChatLineVM> Recent,
    int                       UnreadCount,
    ChatChannel               ActiveInputChannel);
```

Built from `IGameState` each frame (cheap record allocation). Observable
via `IEvents` subscription for panels that want push updates instead of
pull.

**Commands** — user actions going back.

```csharp
public sealed record UseItemCmd(uint ItemGuid);
public sealed record SendChatCmd(ChatChannel Channel, string Text);
public sealed record CastSpellCmd(uint SpellId, uint? TargetGuid);
public sealed record DragItemCmd(uint ItemGuid, uint DestContainerGuid, int Slot);
public sealed record EquipItemCmd(uint ItemGuid, EquipSlot Slot);
```

Dispatched to an `ICommandBus` that routes to the appropriate subsystem
(`WorldSession.SendSelect`, `ChatService.Send`, etc.).

### Layer 3 — UI backend

New module: `src/AcDream.UI.ImGui/`. References `AcDream.UI.Abstractions`.

- Thin adapter: each panel implements an `IPanel` interface — `Draw(VM)`
  method, emits commands on interaction.
- Panels registered into an `IPanelHost` which the backend iterates
  per frame.
- Keyboard / mouse / focus handled by ImGui natively.

Later: `src/AcDream.UI.Retail/` references the same `AcDream.UI.Abstractions`
and implements the same `IPanel` / `IPanelHost` interfaces — but draws
with our own retained-mode toolkit + retail dat assets.

## Plugin API (must be backend-agnostic)

```csharp
public interface IPanel
{
    string Id { get; }
    string Title { get; }
    void   Draw(in PanelContext ctx);
}

public readonly ref struct PanelContext
{
    public readonly IGameState    State;
    public readonly ICommandBus   Commands;
    public readonly IPanelRenderer Renderer;  // drawing primitives
    // (widget calls flow through Renderer so the panel never references
    //  ImGuiNET / Hexa / our custom widget namespaces directly)
}
```

`IPanelRenderer` exposes a retail-UI-friendly primitive set: `Panel`,
`Label`, `Button`, `TextField`, `ScrollView`, `ListView`, `Icon`, `Tab`,
`ProgressBar`, `DragSource`, `DropTarget`. ImGui implementation wraps
ImGui calls; custom implementation uses our retained-mode toolkit.

**Key discipline:** no panel references Hexa.NET.ImGui directly. If a
panel needs a feature the abstraction doesn't expose, add it to
`IPanelRenderer`, don't reach through.

## Implementation order

### Sprint 1 — Infrastructure + first visible panel

1. `AcDream.UI.Abstractions`: `IPanel`, `IPanelHost`, `IPanelRenderer`,
   `ICommandBus`, base ViewModels (start with `VitalsVM` only).
2. `AcDream.UI.ImGui`: Hexa.NET.ImGui wired, `ImGuiPanelRenderer`
   implementation of `IPanelRenderer` (Label, Button, Panel, ProgressBar
   is enough for vitals).
3. `GameWindow`: host the `IPanelHost`; render on top of scene when
   `ACDREAM_DEVTOOLS=1`.
4. `VitalsPanel` — first real panel. Reads HP/stam/mana from
   `IGameState`, renders three progress bars.

**Success criteria:** launch the client, see three coloured bars in the
top-left that actually reflect the character's current vitals as they
walk around / take damage / regen.

### Sprint 2 — Interaction panels

- `ChatPanel` — reads `ChatVM`, emits `SendChatCmd`. `ICommandBus`
  routes to `WorldSession`.
- `InventoryPanel` — reads `InventoryVM`, click-to-select, double-click
  to equip, drag target for future move.
- `CharacterPanel` — attributes, skills, XP.

### Sprint 3 — Plugin API hardening

- Document the `IPanel` contract.
- Port the smoke plugin to register a demo panel via the API.
- Confirm plugins can subscribe to game events AND draw UI through the
  same interface.

### Sprint 4+ — More panels

Spellbook, allegiance, fellowship, trade, map, quest log, options.
Continue to expand `InventoryPanel` with drag-drop, split, appraise.

### Later — Custom retail-look backend

`AcDream.UI.Retail` implements `IPanelRenderer` with our own toolkit +
retail dat assets. Swap panels one at a time. ImGui overlay remains for
devtools.

## Non-goals for this first pass

- **Not** going to theme ImGui to look retail. Waste of effort when we'll
  swap the backend. Devtools aesthetic is fine.
- **Not** porting retail's widget code. We use their ASSETS later, not
  their widget implementation.
- **Not** building layout DSL / XAML-like markup. Panels register and
  draw procedurally, same as ImGui.

## Alternatives considered

| Option | Pros | Cons | Why not picked |
|---|---|---|---|
| ImGui.NET + Silk.NET.OpenGL.Extensions.ImGui | Official Silk.NET path, battle-tested | Lags upstream ImGui, AOT story has sharp edges | Hexa tracks upstream faster, cleaner AOT |
| Myra | Retained-mode, less-debug-y look | Needs a custom Silk.NET backend (~300 LOC), slower iteration | ImGui is faster to first pixel; aesthetics will move to custom anyway |
| Avalonia | Mature, XAML designer, great devtools | Hostile to Silk.NET render loop, huge dep | Integration cost too high, aesthetics wrong |
| NoesisGUI | Slick, XAML-like, production-quality | Commercial license, big dep | Premature optimization |
| RmlUi | HTML/CSS mental model | Bindings immature, own render backend needed | Too much glue |
| Pure custom on Silk.NET from day one | Full control, retail look immediately | Months of work before first visible panel | Can't validate game logic fast enough |

## Risks + mitigations

- **Risk:** `IPanelRenderer` grows to leak ImGui-isms.
  **Mitigation:** code review every addition; if a feature only exists
  in ImGui and the retail toolkit can't express it, don't add it.

- **Risk:** Swap to custom backend breaks a dozen panels simultaneously.
  **Mitigation:** swap one panel at a time, keep ImGui rendering the
  rest until all are ported.

- **Risk:** Plugin authors write panels that only work in ImGui.
  **Mitigation:** smoke plugin registers a panel early; use it as a
  canary whenever backend changes.

- **Risk:** Hexa.NET.ImGui stops being maintained.
  **Mitigation:** integration is small (<100 LOC), switching to
  ImGui.NET is a one-morning operation.

## Open questions (defer to implementation)

- Where does input focus live — ImGui captures keyboard by default when
  a text field is active, does our game-side input system need to check
  "did ImGui want this event"? (Yes, standard pattern. Wire
  `io.WantCaptureKeyboard` gate.)
- Do devtools panels ship in release builds? (Yes, gated on env var, cost
  is negligible when disabled.)
- Modal dialogs? Drag-drop? Fleshed out in Sprint 2 when we have
  inventory actually working.