acdream/docs/superpowers/specs/2026-06-21-d2b-inventory-controller-design.md

D.2b Sub-phase B-Controller — inventory population design

Date: 2026-06-21 Phase: D.2b retail-UI engine → core panels → Sub-phase B (inventory) → B-Controller Branch: claude/hopeful-maxwell-214a12 Predecessor: B-Grid (sub-window mount + UiItemList grid mode) + #145 (ZLevel z-order) — shipped. Handoff: docs/research/2026-06-21-d2b-bgrid-shipped-bcontroller-next-handoff.md.

0. Goal

Make the F12 inventory window show the player's live contents. Bind the imported gmInventoryUI (LayoutDesc 0x21000023) tree by element id and populate it from ClientObjectTable:

1. the "Contents of Backpack" grid with the player's pack items,
2. the right-strip pack-selector (main-pack cell + side-bag container icons),
3. the vertical burden meter + the % text,
4. the Type-0 captions ("Burden", "Contents of Backpack").

This is the gmInventoryUI::PostInit / gmBackpackUI::PostInit / gm3DItemsUI::PostInit analogue. Read-only: no container switching, no drag-as-source, no wield/drop wire (those are B-Wire / B-Drag / Sub-phase C).

Both scope calls were taken by the user during brainstorming: faithful pack-selector (populate the right strip too) and full faithful burden meter (vertical fill + ported InqLoad formula).

1. The inventory tree (confirmed by dat dump + decomp)

gmInventoryUI 0x21000023 (300×362) is a frame nesting three sub-windows (mounted by B-Grid's sub-window mount; all reachable via ImportedLayout.FindElement):

Sub-window	LayoutDesc	Mounted at	Size	This phase
paperdoll	0x21000024	0x100001CD	224×214	Sub-phase C (not here)
backpack strip	0x21000022	0x100001CE	61×339	here
3D-items ("Contents of Backpack")	0x21000021	0x100001CF	234×120	here

Elements this controller binds

Id	Role	Resolved widget	Source
0x100001C6	3D-items contents grid (192×96)	UiItemList (grid)	gm3DItemsUI::PostInit m_itemList DynamicCast(0x10000031) (decomp 176734-176742)
0x100001C5	"Contents of Backpack" caption (192×15)	Type-0 → caption pass	gm3DItemsUI::PostInit m_contentsText, SetText 176745
0x100001CA	backpack m_containerList (36×252, 1 col)	UiItemList (grid)	gmBackpackUI::PostInit DynamicCast(0x10000031) (176621-176629)
0x100001C9	backpack m_topContainer (36×36, 1 cell)	UiItemList (single)	gmBackpackUI::PostInit (176612-176620)
0x100001D9	burden meter (vertical 11×58, Type 7)	UiMeter	gmBackpackUI::PostInit DynamicCast(7) (176601-176610)
0x100001D8	burden % text (36×15)	Type-0 → caption pass	gmBackpackUI m_burdenText, SetText "%d%%" (176583)
0x100001D7	"Burden" caption (36×15)	Type-0 → caption pass	dat

The three list elements (0x100001C6/C9/CA) are Type-0 in the dat, inheriting BaseElement 0x10000339 / BaseLayoutId 0x2100003D (the UIElement_ItemList prototype) → ElementReader.Merge resolves them to Type 0x10000031 → DatWidgetFactory builds them as UiItemList. Already verified reachable by id through the mount.

2. Architecture

New src/AcDream.App/UI/Layout/InventoryController.cs, mirroring ToolbarController / VitalsController (Code-Structure Rule 1 — no new feature body in GameWindow):

public sealed class InventoryController
{
    public static InventoryController Bind(
        ImportedLayout invLayout,
        ClientObjectTable objects,
        Func<uint> playerGuid,               // _playerServerGuid
        Func<ItemType,uint,uint,uint,uint,uint> iconIds,   // IconComposer.GetIcon
        Func<int?> strength,                 // LocalPlayerState Strength.Current
        UiDatFont? datFont);
    public void Dispose();                   // unsubscribe (controllers currently don't, but
                                             // the inventory rebuild is event-driven — be tidy)
}

Bound inline in GameWindow's existing inventory-init block (the invLayout local from B-Grid, GameWindow.cs ~2141), right after RegisterWindow(WindowNames.Inventory, …) — exactly where ToolbarController.Bind(toolbarLayout, …) sits for the toolbar.

Lifecycle: Bind find-by-id binds all elements, subscribes to objects.ObjectAdded/ObjectMoved/ObjectRemoved and LocalPlayerState attribute/Changed events, then calls Populate() once. Each subscription calls Populate() (filtered: only when the changed object is in the player's possession subtree, mirroring ToolbarController.Populate's IsShortcutGuid gate). Missing elements are skipped silently (partial-layout tolerance, like SelectedObjectController).

3. Population (Populate())

Reads var contents = objects.GetContents(playerGuid()) (→ IReadOnlyList<uint>, slot-ordered). Partition each guid's ClientObject:

• side bag = Type.HasFlag(ItemType.Container) OR ItemsCapacity > 0.
• loose item = everything else.

Then:

• 3D-items grid 0x100001C6 — Columns=6, CellWidth=CellHeight=32 (192÷32=6 cols × 96÷32=3 rows; cell template UIItem 0x21000037 = 32×32). Flush(), then AddItem(new UiItemSlot{…}) + cell.SetItem(guid, iconIds(item.Type, item.IconId, item.IconUnderlayId, item.IconOverlayId, item.Effects)) per loose item. (Pitch 32 vs 36 → visual-confirm; 192/32=6 is the clean fit and matches the handoff "6 cols" note.) Overflow past 3 rows is clipped by the panel for now; scroll = follow-up (the 0x100001C7 gutter is the scrollbar).
• m_containerList 0x100001CA — Columns=1, 32px cells. One cell per side bag, same SetItem. Empty on a char with no side bags (correct).
• m_topContainer 0x100001C9 — single cell = the main pack. Icon: a fixed backpack RenderSurface DID (pin from the decomp / a known UI icon; if none found, leave the empty-slot art and file a follow-up — do NOT invent a guid). Bound object id = playerGuid() (the main pack ≡ the player container).

Reuse the shipped UiItemList grid mode (Columns/CellWidth/CellHeight/Flush/AddItem) and UiItemSlot.SetItem(guid, tex) + IconComposer.GetIcon. Do not rebuild the spine.

4. Burden meter (faithful vertical port)

4.1 Retail formula (ported, with anchors)

gmBackpackUI::SetLoadLevel(double load) (decomp 176536, 0x004a6ea0):

• fill = clamp(load × 0.3333…, 0, 1) → pushed to the meter as float attribute 0x69 (UIElement::SetAttribute_Float, 176565-176573).
• % text = floor((load×⅓) × 300) = floor(load × 100) formatted "%d%%" → UIElement_Text::SetText(m_burdenText) (176576-176583).

load = CACQualities::InqLoad() (decomp 409756, 0x0058f130):

strength = InqAttribute(1)            // primary attr 1 = Strength, default 10
aug      = InqInt(0xE6)               // capacity augmentation, default 0
capacity = EncumbranceSystem::EncumbranceCapacity(strength, aug)
burden   = InqInt(5)                  // PropertyInt 5 = EncumbranceVal (total carried)
load     = EncumbranceSystem::Load(capacity, burden)

EncumbranceSystem::EncumbranceCapacity(str, aug) (decomp 256393, 0x004fcc00):

if str <= 0: return 0
bonus = clamp(aug × 30, 0, 150)       // 0x1e=30, cap 0x96=150
return str × 150 + bonus × str        // = str × (150 + bonus)

EncumbranceSystem::Load(capacity, burden) (decomp 256413, 0x004fcc40): the decompiler mangled the FP body to if cap<=0 return cap; return burden; the structure (a divide-by-zero guard + a single divide) is unambiguously load = burden / capacity — the encumbrance ratio (1.0 = at capacity, up to ~3.0). Cross-ref: matches acdream's existing BurdenMath.ComputeMax = 150×str + str×bonus (ClientObject.cs:215) and the r06 research doc ("maxBurden = 150 × Strength + Strength × bonusBurden; carry limit 3 × maxBurden"). ACE was not checked out in this worktree; the decomp + existing port + r06 doc are three corroborating sources.

acdream port: maxBurden = BurdenMath.ComputeMax(strength, bonus) (reuse; bonus = clamp(aug×30,0,150), aug from player PropertyInt 0xE6, default 0 → str×150). load = burden / maxBurden. fill = clamp(load/3, 0, 1). %text = floor(load×100).

4.2 Burden data source

acdream does not track the player's wire EncumbranceVal today (WorldSession parses only per-item Burden). Priority:

1. player ClientObject's PropertyInt 5: objects.Get(playerGuid())?.Properties.GetInt(5) — populated iff PD/0x02CE carried it (B-Wire guarantees this later).
2. fallback: client-side sum of carried Burden over the player's possession subtree (GetContents(player) + recurse side bags + items with WielderId == player).
3. neither → currentBurden = 0 → bar empty / "0%" (correct "no data" state).

strength from LocalPlayerState.GetAttribute(Strength)?.Current (default 10 if absent, matching InqAttribute's 0xa default). Divergence row if (2) is used (client recompute vs server EncumbranceVal — same quantity).

Drive the meter via UiMeter.Fill = () => fill and a Label/caption provider for the % text, recomputed on ObjectAdded/Moved/Removed + LocalPlayerState.Changed/AttributeChanged.

4.3 Vertical fill (the one UiMeter change)

Per UIElement_Meter::DrawChildren (decomp 123574, 0x0046fbd0): the meter draws its own DirectState media as the track (full) and the m_pcChildImage child clipped to attribute 0x69 (the fill fraction). So BuildMeter's existing single-image assignment is already correct (meter-own 0x0600121D → BackTile/track; child 0x0600121C → FrontTile/fill). No sprite-role change.

The clip axis/direction is m_eDirection (read from LayoutDesc property 0x6f at UIElement_Meter::Initialize, decomp 123334-123336): 1=L→R, 2=T→B, 3=R→L, 4=B→T. UiMeter is hardcoded 1. Add:

• a UiMeter.Vertical (or Direction) flag,
• a DrawVBar that draws BackTile over the full rect then FrontTile clipped to Height × fraction along the fill direction. The burden child sprite (11×61) ≈ the bar (11×58) — effectively single-sprite, no 3-slice tiling needed.

Direction source: read property 0x6f if ElementReader surfaces it; else infer vertical from Width < Height and default B→T (dir 4) — the AC convention for a vertical resource bar — with a visual-confirm and an AP register row for the geometry-inference. (Reading 0x6f is preferred; decide in the plan based on how cheaply ElementReader can expose it.)

5. Captions (Type-0 text)

Controller caption pass (not a factory Type-0→UiText promotion — that would risk other panels' inert Type-0 elements). For each caption id, attach a centered UiText child carrying the known string, mirroring SelectedObjectController's name-overlay attach and VitalsController's number overlay:

• 0x100001D7 → "Burden"
• 0x100001C5 → "Contents of Backpack" (procedural in retail via SetText, 176743-176745)
• 0x100001D8 → the live % text (floor(load×100) + "%"), updated with the meter.

Caption strings are hardcoded with their decomp citation (retail sets 0x100001C5/0x100001D8 procedurally; 0x100001D7 "Burden" is the dat element's label). Font = the retail dat font (datFont), color/justification per the Type-0 base (left/normal). If the dat string for 0x100001D7 is trivially readable from the layout, prefer it over the hardcode.

6. Divergence register rows (add in the impl commit)

• AP — burden currentBurden computed client-side (Σ carried Burden) when the wire EncumbranceVal (PropertyInt 5) is absent; retail reads the server-maintained value. Retire when B-Wire parses it.
• AP — capacity augmentation (aug, PropertyInt 0xE6) not tracked → bonus = 0 → un-augmented str×150. Buffed/augmented chars read slightly high.
• AP (only if dir not read from 0x6f) — burden meter orientation inferred from W<H geometry + default B→T, vs retail's m_eDirection from property 0x6f.
• AP — main-pack m_topContainer icon is a fixed/placeholder backpack art, not a weenie-driven icon (the main pack ≡ the player, which has no item IconId).

7. Testing (dat-free conformance)

tests/AcDream.App.Tests/UI/Layout/InventoryControllerTests.cs (+ a burden-math test):

• Bind — given a synthetic ImportedLayout (built via BuildFromInfos from ElementInfo fixtures, or a hand-built tree) with the 7 ids, Bind finds the lists/meter and does not throw on missing ids.
• Grid population — N loose items in GetContents(player) → the 3D grid has N cells with the right guids; M side bags → m_containerList has M cells; partition correctness (container vs loose).
• Burden golden values (Str=100 → max=15000): burden 0 → load 0 → fill 0 / "0%"; 7500 → 0.5 → 0.1667 / "50%"; 15000 → 1.0 → 0.3333 / "100%"; 45000 → 3.0 → 1.0 (clamped) / "300%"; 60000 → 4.0 → 1.0 (clamped) / "400%". Assert fill and %text separately.
• Capacity — EncumbranceCapacity(100, 0)=15000; (100, 3)=15000+min(90,150)·100=24000; (100, 10)=15000+min(300→150)·100=30000; (0, x)=0.
• Vertical fill rect — UiMeter vertical mode: fraction 0.5 of an 11×58 bar fills the correct half along the fill direction.
• Caption — the caption UiText children carry the expected strings.
• Rebuild — firing ObjectAdded for a player-pack item re-runs Populate and the new cell appears; an unrelated guid does not.

Reuse the existing Layout test fixtures (vitals_2100006C.json pattern). A real-dat smoke check of Import(0x21000023) + Bind is a nice-to-have before wiring (not gating).

8. Visual verification (final launch — folded with the z-order eyeball)

Launch with ACDREAM_RETAIL_UI=1, F12: confirm (a) pack items show in the "Contents of Backpack" grid, (b) side bags (if any) + main-pack cell in the right strip, (c) the burden bar fills vertically the right direction with the right sprites and the % reads sanely, (d) the "Burden"/"Contents of Backpack" captions render, AND (e) chat + toolbar show no #145 z-order regression. Items (c) direction and (a) cell pitch are the two visual-confirm unknowns.

9. Acceptance criteria

• InventoryController binds 0x21000023's tree by id; build + tests green.
• 3D-items grid populates from GetContents(player) loose items; right strip from side bags + main pack.
• Burden meter renders vertically with the ported formula; % text correct; golden tests pass.
• Captions render.
• Every ported AC algorithm cites its decomp anchor in comments; divergence rows added.
• Visual verification (with the z-order eyeball) by the user.

10. Out of scope (explicit non-goals → later sub-phases)

• Container switching (click a pack-selector cell → re-point the 3D grid). → interactivity.
• Inventory cell as a drag source (SourceKind==Inventory). → B-Drag.
• Wire gaps (DropItem/GetAndWieldItem/ViewContents/SetStackSize/player EncumbranceVal parse). → B-Wire.
• Paperdoll doll + per-slot equip art (0x10000032 UiItemSlot registration). → Sub-phase C.
• Scrolling the contents grid past 3 rows.