acdream/docs/superpowers/specs/2026-06-18-d54-object-item-model-design.md

D.5.4 — Client object/item data model (foundation) — design

Date: 2026-06-18 Status: design approved (brainstorm) → spec under review → writing-plans next Phase: D.5.4 — the data-model foundation under D.5 "Core panels" (D.2b retail-look track). Registered in the roadmap D.5 sub-phase ledger; blocks D.5.5+ (inventory / paperdoll / vendor / trade panels resolve items from this table). Branch: claude/hopeful-maxwell-214a12 (D.5.1 + D.5.2 already landed here; this continues it). User constraint: "architecturally solid, no quick fixes" — do NOT band-aid EnrichItem to add new items; design the model properly.

Research evidence base (this spec cites; it does not re-derive):

• docs/research/2026-06-18-item-object-model-handoff.md — the phase framing + the crux
• docs/research/deepdives/r06-items-inventory.md — item/property/container model + PublicWeenieDesc wire layout (§4) + burden (§6) + 2-deep containers (§7)
• docs/research/2026-06-16-ui-item-slot-icon-dragdrop-spine-deep-dive.md — ClientObjMaintSystem / resolve-by-guid model
• docs/research/2026-06-16-inventory-deep-dive.md — inventory wire catalog + container learning
• The named-retail decomp acclient_2013_pseudo_c.txt / acclient.h (the oracle for the two-table model)

---

1. Goal

Replace acdream's enrich-existing-only item scaffold with retail's canonical-create object model. Today ItemRepository.EnrichItem (ItemRepository.cs:162) returns false and silently drops a CreateObject for any item that wasn't pre-seeded as a stub from PlayerDescription — so items acquired mid-session, ground items, vendor items, and pack items the login snapshot didn't enumerate never enter the model and render no icon (confirmed live on Coldeve, character Barris: 4 of 6 hotbar slots blank).

After this phase: CreateObject (0xF745) is the canonical create-or-update for every server object, the data table holds the data side of every object (items and creatures alike), PlayerDescription/shortcuts are references, the container membership index is live, and all UI resolves objects by guid. The Coldeve blank-icon bug is fixed at the root, and the foundation D.5.5's panels sit on is in place.

This is a data-model + ingestion phase. No new panels ship; the toolbar (D.5.1) is the only live consumer and must keep working (visually unchanged).

2. The crux — settled (the three brainstorm decisions)

The handoff's §2 framing ("retail unifies everything under one ClientObjMaintSystem") was a misread. The named decomp shows retail is a two-table design, and the brainstorm settled the architecture against that ground truth:

1. Two tables, fix ingestion (not unify). Retail's CObjectMaint holds two hash tables keyed by the same guid — object_table (CPhysicsObj, render/physics) and weenie_object_table (ACCWeenieObject, data/UI) — cross-linked by pointer, created and destroyed together. The UI only calls GetWeenieObject(guid); physics only calls GetPhysicsObject(guid). acdream's existing WorldEntity + item-table split already mirrors this. We keep them separate (joined by guid) and fix the ingestion, not the structure. A merge would also violate Code Structure Rule 2 (WorldEntity carries MeshRef/GfxObj dat handles and rendering-coupled AABB math; merging drags GL into AcDream.Core).

2. Complete model + container index. Capture the full item weenie-field set (currently parsed-then-discarded) into the data object, maintain a live container-membership index (containerGuid → ordered items), evict on DeleteObject, fix the WeenieClassId misuse, and expose a formal resolve-by-guid surface. Defer only the panel UIs and panel-driven flows to D.5.5.

3. All objects (true weenie table). CreateObject upserts every object (creatures, players, NPCs, items) into the data table, making it acdream's ACCWeenieObject-equivalent and retiring the redundant GameWindow._liveEntityInfoByGuid (Name+ItemType duplicate) so selection/target also resolves from the one table. End state = exactly retail's two tables.

3. Retail anchors (the load-bearing facts)

All from the named decomp (acclient_2013_pseudo_c.txt / acclient.h), verified during the D.5.4 code-map research:

• Two parallel tables, one manager. CObjectMaint (acclient.h:33078) holds object_table : LongHash<CPhysicsObj>, weenie_object_table : LongHash<CWeenieObject>, matching null_object_table / null_weenie_object_table placeholders (for out-of-order create), visible_object_table, and object_inventory_table : LongHash<CObjectInventory> (the per-container contents lists). Both object tables keyed by the same uint32 guid.
• CreateObject is create-OR-update (timestamp-driven upsert), not create-only. SmartBox::HandleCreateObject (decomp ~93740) first calls CObjectMaint::GetObjectA(guid, &phys, &weenie) (the 3-arg overload, ~269768) to detect whether either table already has the guid. Fresh → ACCObjectMaint::CreateObject (~356155) which allocates the ACCWeenieObject (ACCFactory::MakeCWeenieObject_Internal, 0x150 bytes, ~354698), inserts it, fills pwd via SetWeenieDesc, cross-links, and inserts the CPhysicsObj. Existing → the update branch patches in place via SetWeenieDesc (data) + per-timestamp physics updates. There is no full-object replace — updates merge.
• The weenie object holds all item game-data in pwd (PublicWeenieDesc, acclient.h:37163+): _iconID/_iconOverlayID/_iconUnderlayID, _effects, _type, _stackSize/_maxStackSize, _value, _burden, _containerID/_wielderID/_location/_priority, _itemsCapacity/_containersCapacity, _structure/_maxStructure, _workmanship, …
• Every object is an ACCWeenieObject — creatures/players included; the UI resolves a selected creature's name/health from the same table via GetWeenieObject.
• DeleteObject frees both objects atomically (ACCObjectMaint::DeleteObject ~355020 → CObjectMaint::DeleteObject(guid) ~270149) — physics and weenie removed in one call.
• The wire layout of the PublicWeenieDesc flag-gated tail is r06 §4; acdream's CreateObject.cs:558-806 already walks every field in exact ACE order (it skips the ones it doesn't keep — capturing them is changing pos += N to read the value).

4. Scope

In scope (D.5.4):

• Rename + broaden: ItemRepository → ClientObjectTable, ItemInstance → ClientObject, events Item* → Object*. The data table holds the data side of all server objects.
• CreateObject.TryParse captures the full item field set (see §6.1) — currently discarded.
• Upsert is a field-level merge (create-if-absent, else patch wire-carried fields in place, preserving the PropertyBundle and move-state). EnrichItem is deleted.
• Ingestion wiring moves off GameWindow into AcDream.Core.Net (ObjectTableWiring): CreateObject→upsert, DeleteObject→remove, the 0x02CE UiEffects path→UpdateIntProperty.
• Container membership index (containerGuid → ordered item guids), live on upsert + move + remove, exposed via GetContents(guid).
• WeenieClassId captured from CreateObject (stop misusing PlayerDescription's ContainerType as the class id).
• PlayerDescription becomes a membership manifest (records "this guid is mine / in container / equipped at slot"); out-of-order with CreateObject is safe (whichever arrives first creates the entry, the other merges).
• Retire GameWindow._liveEntityInfoByGuid; migrate its consumers (IsLiveCreatureTarget/DescribeLiveEntity/target-indicator) to ClientObjectTable.Get.
• ToolbarController resolves via ClientObjectTable.Get and filters its event handler by guid (only re-binds when a changed guid is one of its 18 shortcuts).
• DeleteObject (0xF747) evicts from the table.
• Conformance tests throughout (§8). Preserve the D.5.2 effects-contract tests.

Out of scope (D.5.5+, explicit non-goals):

• The panel UIs themselves (inventory / paperdoll / vendor / trade / spellbook).
• ViewContents (0x0196) open/close flow + the still-unwired inbound move events (InventoryPutObjectIn3D 0x019A, CloseGroundContainer 0x0052, InventoryServerSaveFailed 0x00A0) and their builders (DropItem/GetAndWieldItem/ NoLongerViewingContents).
• Drag-drop mutate wire (AddShortcut/RemoveShortcut, PutItemInContainer from UI, etc.).
• ShortCutManager durable persistence (shortcuts stay in the current closure path).
• The broader PublicUpdateProperty* family beyond the existing UiEffects (0x02CE) path (live StackSize/Value/Structure updates) — captured at create time, but the per-property live-update parsers are D.5.5/M2.
• null_object_table-style pre-queuing of a child CreateObject that arrives before its parent. (Our upsert already makes plain out-of-order PD↔CreateObject safe; the parent/child parenting edge case is deferred — see §10 risks.)

5. Architecture & components

Two guid-keyed tables, joined by guid, both mutated on the render thread:

Table	acdream type	retail analogue	holds	layer
Render/physics	WorldEntity (+ GpuWorldState)	object_table / CPhysicsObj	mesh, position, AABB, cell	AcDream.Core/World + AcDream.App
Data/UI	ClientObjectTable of ClientObject	weenie_object_table / ACCWeenieObject	icon, name, type, stack, value, container/equip, properties	AcDream.Core/Items (pure data)

Components (file → responsibility → change):

1. ClientObject (AcDream.Core/Items/ItemInstance.cs → renamed file/type from ItemInstance). Per-object data record. Change: add the §6.1 fields; make WeenieClassId settable; keep PropertyBundle. Item-specific fields are simply unset for creatures (faithful to retail's ACCWeenieObject for non-items).

2. ClientObjectTable (AcDream.Core/Items/ItemRepository.cs → renamed). The guid-keyed store + container index + event surface. Change:

   • AddOrUpdate becomes a field-level merge upsert (§7.2), not a whole-object replace.
   • Add the container index: Dictionary<uint, List<uint>> keyed by containerGuid, kept ordered by slot; updated on upsert / MoveItem / Remove; exposed via IReadOnlyList<uint> GetContents(uint containerGuid).
   • Events renamed ObjectAdded/ObjectUpdated/ObjectRemoved/ObjectMoved.
   • EnrichItem deleted.
   • Keep ConcurrentDictionary (plugin reads) + GetItem→Get resolve surface.

3. ObjectTableWiring (new, AcDream.Core.Net/ObjectTableWiring.cs). Static Wire(WorldSession session, ClientObjectTable table) subscribing the WorldSession GameMessage-level events: EntitySpawned→AddOrUpdate(merge), EntityDeleted→Remove, ObjectIntPropertyUpdated→UpdateIntProperty. This is the seam that moves item ingestion off GameWindow (Rule 1) while keeping AcDream.Core GL-free (Rule 2).

4. CreateObject.cs (AcDream.Core.Net/Messages). Change: capture the §6.1 fields into Parsed (extend the record); the wire-cursor walk already exists — replace the pos += N skips with value reads. Risk: the Parsed positional ctor + WorldSession.EntitySpawn mirror must both grow; cursor arithmetic must stay byte-identical (locked by tests).

5. WorldSession.EntitySpawn (AcDream.Core.Net/WorldSession.cs:47). Change: add the new fields so they reach the ingestion wiring.

6. GameEventWiring.cs (AcDream.Core.Net). Change: PlayerDescription handler stops creating "source of truth" stubs with WeenieClassId = ContainerType; instead it records membership (a merge upsert that sets container/equip placement + marks the guid as the player's). WieldObject/InventoryPutObjInContainer → MoveItem stays (already wired).

7. GameWindow.cs (AcDream.App). Change: delete the EnrichItem call; construct ClientObjectTable + call ObjectTableWiring.Wire; retire _liveEntityInfoByGuid and point its consumers at ClientObjectTable.Get. Render-entity build is unchanged.

8. ToolbarController.cs (AcDream.App/UI/Layout). Change: resolve via ClientObjectTable.Get; event handler filters by guid (only re-bind affected shortcut slots); subscribe to ObjectRemoved too (today it doesn't, leaving stale slots).

9. IconComposer.cs — unchanged (takes fields, not the table).

6. Data model

6.1 ClientObject fields to add (capture from CreateObject)

The ClientObject type already declares most of these fields (they exist on today's ItemInstance), but CreateObject does not populate them — it walks past them on the wire. This table is the wire-capture work: rows marked new also need a field added to the type; the rest just need the parser to read the value into the existing field instead of skipping it. The cursor walk already exists in CreateObject.cs:558-806 (each field has a pos += N skip today). Wire bits per r06 §4 / PublicWeenieDesc:

Field	Wire bit	field state	Notes
WeenieClassId	fixed prefix PackedDword (CreateObject.cs:538)	make settable	discarded today; init-only on the type
Value	0x00000008	exists	pos += 4 today
StackSize / StackSizeMax	0x00001000 / 0x00002000	exists	skipped today
Burden	0x00200000	exists	skipped today
ContainerId	0x00004000	exists	item's parent container guid (drives the index)
ValidLocations	0x00010000	exists	EquipMask (paperdoll needs it)
CurrentWieldedLocation	0x00020000	exists → CurrentlyEquippedLocation	EquipMask
ItemsCapacity / ContainersCapacity	0x00000002 / 0x00000004	new	feed Container (u8 each)
WielderId	0x00008000	new	equip placement
Priority (ClothingPriority)	0x00040000	new	layer order
Structure / MaxStructure	0x00000400 / 0x00000800	new	charges/uses
Workmanship	0x01000000 (f32)	new	salvage/tinker display

ContainerType (PD inventory entry, 0/1/2) moves to its own field on the entry/Container, no longer aliased onto WeenieClassId.

6.2 Container index

ClientObjectTable maintains the equivalent of retail's object_inventory_table: containerGuid → ordered list of item guids (ordered by ContainerSlot). It is derived data, rebuilt from each object's ContainerId/ContainerSlot:

• on upsert: if the object has a non-zero ContainerId, (re)index it under that parent.
• on MoveItem: remove from old container list, add to new (or to equip if WielderId).
• on Remove: drop from its container list.
• expose GetContents(containerGuid) → ordered item guids (inventory panel reads this).

Equip placement (WielderId + CurrentWieldedLocation) is tracked the same way so paperdoll can ask "what's equipped in slot X" without scanning.

7. Ingestion lifecycle

7.1 The flow

• CreateObject (0xF745) → WorldSession parses (full field set) → fires EntitySpawned → ObjectTableWiring calls ClientObjectTable.AddOrUpdate(merge) for every object, independent of whether it also becomes a WorldEntity (inventory items have no position). GameWindow keeps its own EntitySpawned subscription for the render-entity build.
• DeleteObject (0xF747) / Pickup → EntityDeleted → ClientObjectTable.Remove(guid) (today this leaks until Clear()). Render teardown unchanged.
• PlayerDescription (0x0013) → membership manifest: a merge upsert that marks each inventory/equipped guid as the player's and records placement (container/equip slot). The data (icon/name/type/…) arrives from CreateObject. Shortcuts stay on the existing path.
• WieldObject 0x0023 / InventoryPutObjInContainer 0x0022 → MoveItem (already wired) → re-parents in the container index.
• PublicUpdatePropertyInt 0x02CE (UiEffects) → UpdateIntProperty (already wired, preserved).

7.2 Upsert = field-level merge (the key correctness rule)

AddOrUpdate must NOT replace the whole object (today's _items[id] = item clobbers appraise PropertyBundle + move-state on a CreateObject re-send; retail's update branch patches via SetWeenieDesc). The merge rule:

• Absent → insert the new object; fire ObjectAdded.
• Present → patch only the wire-carried fields onto the existing object (Name, Type, Icon*, Effects, Stack, Value, Burden, capacities, WeenieClassId, and placement ContainerId/CurrentWieldedLocation/WielderId when the wire carries them); preserve the PropertyBundle (appraise detail) and any state the wire didn't carry; fire ObjectUpdated.
• Effects keeps the D.5.2 contract: assign unconditionally from the parsed value (0 = "no effect", a meaningful state) so re-composition reflects the current server state.

7.3 Out-of-order safety

Because upsert is create-or-merge, the PD↔CreateObject arrival order is irrelevant: whichever arrives first creates the entry; the other merges its fields in. No drops (the root fix for the Coldeve bug), no silent races.

7.4 Threading

Unchanged: the net channel drains on the render-thread OnUpdate; both tables mutate on the render thread; ConcurrentDictionary is retained only for safe plugin reads. Events fire synchronously on the render thread (matching today).

8. Testing (conformance throughout)

xUnit, hand-built byte fixtures (matching CreateObjectTests / ItemRepositoryTests style; no pcap, no Moq). New + changed tests:

• Full-field-capture parse: each new weenie-header field reads correctly; cursor arithmetic stays byte-identical (a packet with a mid-tail field set still reaches IconOverlay/IconUnderlay). Extend CreateObjectTests.
• Upsert creates a brand-new object (no PD stub) — the Coldeve bug; this test would have failed before the fix and locks it.
• Upsert merge preserves PropertyBundle (appraise) + move-state across a CreateObject re-send; does not clobber.
• Out-of-order: CreateObject-before-PD and PD-before-CreateObject converge to identical state.
• Container index: add/move/remove keeps GetContents correct and slot-ordered; 2-deep container depth (r06 §7); equip placement queryable.
• DeleteObject eviction removes from the table + the container index.
• WeenieClassId is the real class id from CreateObject, not the PD ContainerType.
• _liveEntityInfoByGuid retirement regression: selection/describe still resolve name+type for a creature via ClientObjectTable.Get.
• Toolbar guid-filter: an unrelated object's ObjectAdded does not re-bind a shortcut slot; a shortcut's ObjectUpdated does.
• Preserve the D.5.2 effects tests (effects==0 clears; per-pixel tint) under the new merge path.

9. Divergence register

• Retire the enrich-only stopgap rows (the EnrichItem drops-unseeded-items behavior is gone). Delete those rows in the same commit that lands the fix.
• Add a row for the global-event-with-guid-filter consumer model vs. retail's per-object NoticeRegistrar observer dispatch (a deliberate simplification — consumers filter by guid rather than registering per-object observers). Note it; don't hide it.
• Add a row (or note under it) for the deferred null_object_table-style parent/child pre-queue (out-of-order parented create) — see §10.

10. Risks & open questions

• Cursor arithmetic regression in CreateObject.cs is the highest-risk change: turning skips into reads must not shift any offset. Mitigation: the field walk already exists and is test-covered; add per-field value assertions and a "mixed flags reach IconOverlay" test.
• AddOrUpdate merge vs. replace touches existing AddOrUpdate callers (PD seeding, appraise UpdateProperties). Audit every caller; the merge must be a strict superset of prior behavior for the toolbar path.
• Event volume: upserting all objects fires ObjectAdded per creature spawn. The toolbar guid-filter handles it; future panels must filter too (documented in the table's event XML-doc).
• _liveEntityInfoByGuid retirement timing: the ingestion wiring and GameWindow's render handler both subscribe to EntitySpawned; ensure the table is populated before any consumer queries (consumers run on later user interaction, so this is safe, but assert it).
• Parented item ordering (a child CreateObject arriving before its parent) — retail uses null_object_table pre-queuing. Deferred; PD↔CreateObject ordering is handled, but document the parent/child gap so D.5.5 picks it up if a panel needs it.
• Naming churn: the rename touches GameEventWiring, ToolbarController, tests, and the IconComposer call site. Mechanical but wide; do it as a focused rename commit so the diff reads cleanly.

11. Acceptance criteria

• dotnet build + dotnet test green (the full suite, including the new conformance tests).
• A CreateObject for an item with no prior PD stub registers it in the table and the toolbar renders its icon (the Coldeve repro, exercised by a unit test; visual confirmation on a live server is the user's gate).
• The toolbar still renders correctly for pre-seeded items (no regression).
• Selection/target still resolves creature name+type after _liveEntityInfoByGuid retirement.
• Roadmap D.5 ledger updated (D.5.4 → shipped); divergence register rows added/retired; memory digest updated if there's a durable lesson.