7e84d489d0
Landed the UI framework design in 2026-04-24-ui-framework.md yesterday;
this commit propagates the decisions across the documents that future
sessions touch first, so the three-layer pattern is discoverable without
re-reading the full plan.
Changes:
* NEW memory/project_ui_architecture.md — evergreen crib-sheet:
three-layer diagram, AcDream.UI.Abstractions contract, D.2a/D.2b
split, module layout, hard rules, why staged not pure-custom.
* CLAUDE.md: new paragraph describing the three-layer UI split, naming
AcDream.UI.Abstractions as the plugin-facing contract, pointing at
the full plan + memory crib.
* docs/architecture/acdream-architecture.md: new "UI Architecture"
companion-stack diagram after Layer 0-5 (doesn't renumber the main
stack), plus step 6a "UI tick" in Per-Frame Update Order.
* docs/plans/2026-04-11-roadmap.md Phase D tightened:
- D.2 split explicitly into D.2a (Hexa.NET.ImGui scaffold + abstraction
layer) and D.2b (custom retail-look backend, implements same contracts).
- D.3 AcFont / D.4 dat sprites / D.7 cursor flagged as D.2b dependencies.
- D.5 core panels / D.6 HUD flagged as abstraction-layer deliverables
— ship with D.2a, reskinned by D.2b.
- D.8 Sound marked superseded (shipped as Phase E.2).
- F.5 core panels + H.1 chat-window cross-references updated to say
they target AcDream.UI.Abstractions, unblocked by D.2a.
- Shipped-phases table untouched.
* docs/research/retail-ui/00-master-synthesis.md: scope note at top
clarifies the Keystone research is the D.2b (custom backend)
foundation, NOT where D.2a starts.
* ~/.claude/.../memory/MEMORY.md: one-line index entry pointing at the
new project_ui_architecture.md (so session auto-load surfaces it).
Zero code changes; doc-only. dotnet build stays green. All verification
greps pass (see plan file for exact checks).
74 lines
3.6 KiB
Markdown
74 lines
3.6 KiB
Markdown
# 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`](../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): `Hexa.NET.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.
|
|
- **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/` — Hexa.NET.ImGui-based implementation of
|
|
`IPanelRenderer` + ImGui bootstrap. Phase D.2a.
|
|
- `src/AcDream.UI.Retail/` (later) — custom retained-mode toolkit using
|
|
dat assets, same `IPanelRenderer` contract. Phase D.2b.
|
|
|
|
## Hard rules
|
|
|
|
1. **No panel references a backend namespace.** If a panel imports
|
|
`Hexa.NET.ImGui` or a custom-toolkit widget class directly, it's a
|
|
bug.
|
|
2. **Plugin API targets the abstraction layer only.** Plugins define
|
|
`IPanel` instances; they never see which backend draws them.
|
|
3. **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.
|
|
4. **D.3 AcFont / D.4 dat sprites / D.7 cursor manager are D.2b
|
|
dependencies** — they plug into the custom backend only.
|
|
5. **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.
|
|
|
|
## Links
|
|
|
|
- Full design: `docs/plans/2026-04-24-ui-framework.md`
|
|
- Roadmap entry: `docs/plans/2026-04-11-roadmap.md` Phase D (see the
|
|
2026-04-24 callout block).
|
|
- Custom-backend research (applies to D.2b, NOT D.2a):
|
|
`docs/research/retail-ui/00-master-synthesis.md` + slices 01-06.
|