docs(D.2b-A): window manager + F12 inventory toggle design spec
Sub-phase A of the window-manager → inventory → paperdoll arc. A named- window registry on UiRoot (Show/Hide/Toggle/BringToFront) + raise-on-click + wiring the EXISTING InputAction.ToggleInventoryPanel (already F12-bound, retail-faithful) through OnInputAction, toggling a throwaway placeholder inventory window that Sub-phase B replaces with the real gmInventoryUI. Cross-check correction vs the handoff: retail's inventory key is F12, not I (I = Laugh emote per retail-default.keymap.txt:246). Reuses the existing action, so no new keybind — rebindable via the Settings panel. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik
parent
a391b86a2e
commit
8f30585cb0
1 changed files with 245 additions and 0 deletions
245
docs/superpowers/specs/2026-06-20-d2b-window-manager-design.md
Normal file
245
docs/superpowers/specs/2026-06-20-d2b-window-manager-design.md
Normal file
|
|
@ -0,0 +1,245 @@
|
||||||
|
# Design — D.2b window manager (open/close + F12 inventory toggle)
|
||||||
|
|
||||||
|
**Date:** 2026-06-20
|
||||||
|
**Phase:** D.2b retail-UI arc, Sub-phase **A** (window manager) — the first of three
|
||||||
|
(A window manager → B inventory window → C paperdoll). Handoff:
|
||||||
|
`docs/research/2026-06-20-window-manager-inventory-handoff.md` §3.
|
||||||
|
**Status:** approved design, pre-implementation.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Context & goal
|
||||||
|
|
||||||
|
Every retail-UI window today is **always-on at a hardcoded position**: vitals, chat, and
|
||||||
|
the toolbar are added to `_uiHost.Root` unconditionally at startup in the `_options.RetailUi`
|
||||||
|
block of `GameWindow.OnLoad` (grep `_uiHost.Root.AddChild`). `UiHost`/`UiRoot` have **no
|
||||||
|
open/close API** — `UiRoot` exposes the widget tree, input routing, focus, capture, modal,
|
||||||
|
and drag-drop, but nothing to show/hide/raise a named top-level window.
|
||||||
|
|
||||||
|
**Goal:** the minimal shared infrastructure to **open/close a top-level window** and a
|
||||||
|
keybind to **toggle the inventory window**. This is the prerequisite for Sub-phase B
|
||||||
|
(the inventory window) and C (paperdoll) — both need a window that starts hidden and is
|
||||||
|
summoned on demand.
|
||||||
|
|
||||||
|
**Non-goal:** the inventory window's *contents*. Sub-phase A toggles a throwaway
|
||||||
|
**placeholder** window; Sub-phase B replaces its body with the real `gmInventoryUI`
|
||||||
|
layout. See §9.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Scope
|
||||||
|
|
||||||
|
**In scope (A):**
|
||||||
|
- A named-window registry on `UiRoot` with `Show` / `Hide` / `Toggle` / `BringToFront`.
|
||||||
|
- Raise-on-click for top-level windows (retail-faithful window stacking).
|
||||||
|
- F12 → toggle the inventory window, via the **existing** `InputAction.ToggleInventoryPanel`.
|
||||||
|
- A minimal placeholder inventory window (default-hidden) so A is visually verifiable and
|
||||||
|
gives B a concrete mount point.
|
||||||
|
- Unit tests for the registry logic; divergence-register bookkeeping.
|
||||||
|
|
||||||
|
**Out of scope (deferred):**
|
||||||
|
- Inventory window contents, grid, sub-window mount, wire gaps, `InventoryController` → **B**.
|
||||||
|
- Paperdoll / `UiViewport` → **C**.
|
||||||
|
- Disk persistence of open-state + window positions → handoff "Plan-2".
|
||||||
|
- A toolbar inventory *button* (radar/menu buttons) — F12 only for now; the button can be a
|
||||||
|
later cheap addition once the inventory window exists.
|
||||||
|
- Spell bar — explicitly deferred by the handoff.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Architecture decision — registry on `UiRoot`
|
||||||
|
|
||||||
|
`UiRoot` already owns exactly the state a window manager manipulates: the top-level
|
||||||
|
`Children`, `ZOrder` (drives both paint order in `DrawSelfAndChildren` and hit-test order in
|
||||||
|
`HitTestTopDown`), keyboard focus, mouse capture, and the modal overlay. "Show / hide / raise
|
||||||
|
a top-level window" is the job it already does — so the registry lives there.
|
||||||
|
|
||||||
|
This mirrors retail, where the Keystone root (`DAT_00870c2c`) owns the widget tree and window
|
||||||
|
stacking. (Keystone is an external DLL with no decomp, so the manager is **toolkit-defined**,
|
||||||
|
not a byte-faithful port — see §7.)
|
||||||
|
|
||||||
|
**Alternatives considered and rejected:**
|
||||||
|
- **Dedicated `WindowManager` class wrapping `UiRoot`** — cleaner single-responsibility on
|
||||||
|
paper, but it must reach into `UiRoot.Children` / `ZOrder` to mount + raise, so it just
|
||||||
|
borrows `UiRoot`'s internals through a new seam. Ceremony for ~30 lines of logic.
|
||||||
|
- **Thin API on `UiHost`** — `UiHost` is the facade `GameWindow` talks to, but the tree and
|
||||||
|
`ZOrder` live in `UiRoot`; this would be a pure forwarding layer with no added value.
|
||||||
|
|
||||||
|
`UiHost` gets **two convenience forwarders** (`ToggleWindow`, `RegisterWindow`) that delegate
|
||||||
|
to `Root`, because `GameWindow` holds a `UiHost`, not a `UiRoot`, at the call sites.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Components & interfaces
|
||||||
|
|
||||||
|
### 4.1 `UiRoot` window registry
|
||||||
|
|
||||||
|
A private `Dictionary<string, UiElement> _windows` plus:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
/// <summary>Register a top-level window under a name for Show/Hide/Toggle.
|
||||||
|
/// Idempotent (re-register replaces). The dict is the source of truth —
|
||||||
|
/// independent of UiElement.Name, which is init-only and not reassigned here.</summary>
|
||||||
|
public void RegisterWindow(string name, UiElement window);
|
||||||
|
|
||||||
|
/// <summary>Make the named window visible and raise it to the front.
|
||||||
|
/// No-op if unknown. Returns true if a window was shown.</summary>
|
||||||
|
public bool ShowWindow(string name);
|
||||||
|
|
||||||
|
/// <summary>Hide the named window (Visible = false). No-op if unknown.</summary>
|
||||||
|
public bool HideWindow(string name);
|
||||||
|
|
||||||
|
/// <summary>Flip the named window's visibility; Show (raise) if it was hidden,
|
||||||
|
/// Hide if it was visible. Returns the new IsVisible state.</summary>
|
||||||
|
public bool ToggleWindow(string name);
|
||||||
|
|
||||||
|
/// <summary>Set element.ZOrder to one above the current max among top-level
|
||||||
|
/// children, so it paints + hit-tests above its peers.</summary>
|
||||||
|
public void BringToFront(UiElement window);
|
||||||
|
```
|
||||||
|
|
||||||
|
- `Show`/`Hide` only flip `UiElement.Visible`; `Visible` already gates Draw, Tick, and
|
||||||
|
HitTest (all early-return when false), so a hidden window is fully inert — no draw, no
|
||||||
|
input, no tooltip timer.
|
||||||
|
- `RegisterWindow` does **not** add the element to the tree — the caller mounts it with
|
||||||
|
`AddChild` (so registration and tree-membership stay independent and the caller controls
|
||||||
|
initial `Visible`). Registration only records the name→element mapping.
|
||||||
|
- `BringToFront`: `window.ZOrder = 1 + max(child.ZOrder for child in Children)`. The existing
|
||||||
|
default windows mount at `ZOrder = 0`, so an opened/clicked window rises above them.
|
||||||
|
|
||||||
|
### 4.2 Raise-on-click
|
||||||
|
|
||||||
|
In `UiRoot.OnMouseDown`, after the existing `FindWindow(target)` resolves the top-level
|
||||||
|
window under the press, call `BringToFront(window)` so the clicked window comes to the top of
|
||||||
|
the stack (retail raises clicked windows). This is the existing `FindWindow` result reused —
|
||||||
|
~3 lines, no new traversal. Applies to **any** top-level window (vitals, chat, toolbar,
|
||||||
|
inventory), not just registered ones; the registry is only for named Show/Hide/Toggle.
|
||||||
|
|
||||||
|
### 4.3 `UiHost` forwarders
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
public void RegisterWindow(string name, UiElement window) => Root.RegisterWindow(name, window);
|
||||||
|
public bool ToggleWindow(string name) => Root.ToggleWindow(name);
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.4 F12 wiring — `OnInputAction`
|
||||||
|
|
||||||
|
`InputAction.ToggleInventoryPanel` already exists, is already bound to **F12** in
|
||||||
|
`KeyBindings.RetailDefaults()` (matching `docs/research/named-retail/retail-default.keymap.txt`
|
||||||
|
line 149: `ToggleInventoryPanel [ "" [ 0 DIK_F12 ] ]`), and is already listed in the Settings
|
||||||
|
rebind UI — so it's user-rebindable with no new wiring. Today **nothing consumes it.**
|
||||||
|
|
||||||
|
Add one arm to the `switch (action)` in `GameWindow.OnInputAction` (the `InputDispatcher.Fired`
|
||||||
|
multicast subscriber; the switch begins at GameWindow.cs:11421):
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
case AcDream.UI.Abstractions.Input.InputAction.ToggleInventoryPanel:
|
||||||
|
_uiHost?.ToggleWindow(WindowNames.Inventory);
|
||||||
|
break;
|
||||||
|
```
|
||||||
|
|
||||||
|
- Gating is already correct: the dispatcher is suppressed by `WantsKeyboard` when the chat
|
||||||
|
input holds focus, so F12 cannot toggle inventory while you're typing.
|
||||||
|
- `WindowNames.Inventory` is a `const string "inventory"` (a small `WindowNames` holder in
|
||||||
|
`AcDream.App.UI`), so the mount, the registry, and the toggle agree on one literal.
|
||||||
|
|
||||||
|
### 4.5 Placeholder inventory window mount
|
||||||
|
|
||||||
|
In the `_options.RetailUi` block of `GameWindow.OnLoad`, alongside the vitals/chat/toolbar
|
||||||
|
mounts, build a minimal framed window:
|
||||||
|
|
||||||
|
```csharp
|
||||||
|
var inventoryWindow = new AcDream.App.UI.UiNineSlicePanel(ResolveChrome)
|
||||||
|
{
|
||||||
|
Left = 200, Top = 120, Width = 320, Height = 400,
|
||||||
|
Visible = false, // starts hidden; F12 reveals it
|
||||||
|
Draggable = true,
|
||||||
|
Anchors = AcDream.App.UI.AnchorEdges.None,
|
||||||
|
};
|
||||||
|
_uiHost.Root.AddChild(inventoryWindow);
|
||||||
|
_uiHost.RegisterWindow(AcDream.App.UI.WindowNames.Inventory, inventoryWindow);
|
||||||
|
```
|
||||||
|
|
||||||
|
This uses the same `UiNineSlicePanel(ResolveChrome)` + `RetailChromeSprites.Border` chrome
|
||||||
|
the vitals/chat windows use, so the placeholder already has the retail beveled frame. It is
|
||||||
|
**throwaway scaffolding**: Sub-phase B replaces the body (and likely the whole construction)
|
||||||
|
with the real `gmInventoryUI 0x21000023` nested layout, keeping the same registry name so the
|
||||||
|
F12 wiring is untouched.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Persistence
|
||||||
|
|
||||||
|
In-memory for the session only. Open/closed state lives in `UiElement.Visible`; window
|
||||||
|
positions are the hardcoded mount positions (already reset each session). No disk persistence
|
||||||
|
— deferred to the handoff's Plan-2.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Testing
|
||||||
|
|
||||||
|
Unit tests in `tests/AcDream.App.Tests/UI/UiRootInputTests.cs` (or a sibling
|
||||||
|
`UiRootWindowManagerTests.cs`) — the registry logic is pure (no GL), so it tests directly:
|
||||||
|
|
||||||
|
- `RegisterWindow` + `ToggleWindow` flips `Visible` false→true→false and returns the new state.
|
||||||
|
- `ShowWindow` raises `ZOrder` above all peers; `HideWindow` sets `Visible=false` without
|
||||||
|
touching `ZOrder`.
|
||||||
|
- `BringToFront` on the lowest window makes its `ZOrder` strictly greatest among siblings.
|
||||||
|
- `ToggleWindow`/`ShowWindow`/`HideWindow` on an unknown name are no-ops returning false.
|
||||||
|
- Raise-on-click: an `OnMouseDown` on a registered window with a peer in front leaves the
|
||||||
|
clicked window with the greatest `ZOrder` (reuses the existing `UiRootInputTests` harness
|
||||||
|
pattern for synthesizing mouse events).
|
||||||
|
|
||||||
|
`dotnet build` + `dotnet test` green (full suite, currently 2752+).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Divergence register
|
||||||
|
|
||||||
|
The window manager is **toolkit-defined** — retail's window stacking lives in `keystone.dll`
|
||||||
|
(no decomp), so this is the existing IA-12 / IA-15 toolkit-adaptation umbrella, not a
|
||||||
|
byte-faithful port. Confirm whether an existing register row covers
|
||||||
|
"retail-UI windows are toolkit-managed, not Keystone-ported"; if not, add a one-line row in
|
||||||
|
`docs/architecture/retail-divergence-register.md` in the implementation commit. **F12 itself
|
||||||
|
is retail-faithful** (matches the retail default keymap) — no divergence for the keybind.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Acceptance criteria
|
||||||
|
|
||||||
|
- `dotnet build` green; `dotnet test` green.
|
||||||
|
- With `ACDREAM_RETAIL_UI=1`, pressing **F12** shows the placeholder inventory window above
|
||||||
|
vitals/chat/toolbar; pressing **F12** again hides it.
|
||||||
|
- Clicking any window (vitals, chat, toolbar, inventory) raises it above the others.
|
||||||
|
- F12 does **nothing** while the chat input is focused (write mode).
|
||||||
|
- Window manager logic is unit-tested; divergence-register row confirmed/added.
|
||||||
|
- Visual verification by the user (the toggle + raise behavior).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Seam for Sub-phase B
|
||||||
|
|
||||||
|
A leaves B a clean handoff:
|
||||||
|
- The registry name `WindowNames.Inventory` and the F12 → `ToggleWindow` wiring are stable;
|
||||||
|
B keeps both.
|
||||||
|
- B replaces the placeholder `UiNineSlicePanel` with the real `gmInventoryUI 0x21000023`
|
||||||
|
nested layout (paperdoll + backpack + 3D-items), re-registering it under the same name.
|
||||||
|
- B adds the dat **close button** → `HideWindow(WindowNames.Inventory)` wiring (the manager
|
||||||
|
already exposes `HideWindow`; A leaves the placeholder closable only via F12).
|
||||||
|
- B wires the inventory cell as a drag **source**, completing B.2's drag-from-inventory via
|
||||||
|
the `SourceKind == Inventory` branch in `ToolbarController.HandleDropRelease`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. References
|
||||||
|
|
||||||
|
- Handoff: `docs/research/2026-06-20-window-manager-inventory-handoff.md` §3 (Sub-phase A).
|
||||||
|
- Retail keymap: `docs/research/named-retail/retail-default.keymap.txt` lines 139–153
|
||||||
|
(panel-toggle commands; inventory = F12) + line 246 (`Laugh` = `DIK_I`).
|
||||||
|
- Toolkit: `src/AcDream.App/UI/UiRoot.cs`, `UiElement.cs`, `UiHost.cs`,
|
||||||
|
`UiNineSlicePanel.cs`; `claude-memory/project_d2b_retail_ui.md`.
|
||||||
|
- Input pipeline: `OnInputAction` switch at `src/AcDream.App/Rendering/GameWindow.cs:11421`;
|
||||||
|
`InputAction.ToggleInventoryPanel`; `KeyBindings.cs:205`;
|
||||||
|
`claude-memory/project_input_pipeline.md`.
|
||||||
|
- Object model (for B): `claude-memory/project_object_item_model.md`,
|
||||||
|
`src/AcDream.Core/Items/ClientObjectTable.cs`.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue