erik/acdream
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

docs(D.5.2): implementation plan (9 TDD tasks) + spec wiring fix

Browse source 
Bite-sized TDD plan for the stateful item-icon system. Corrects spec 5.8:
the live 0x02CE event binds in GameWindow (next to VitalUpdated), not
GameEventWiring (which only handles the 0xF7B0 GameEvent dispatcher).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-06-17 18:19:26 +02:00
parent 419c3ac40c
commit 52306d9268
2 changed files with 981 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

973
docs/superpowers/plans/2026-06-17-d2b-stateful-icon.md Normal file
View file

@ -0,0 +1,973 @@
# Stateful item-icon system (D.5.2) — Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Make the item icon a live function of the item's state — capture the discarded `UiEffects` bitfield, build retail's faithful effect-recolor in the icon compositor, and wire the live `PublicUpdatePropertyInt(0x02CE)` update so the icon re-composites in real time.
**Architecture:** `UiEffects` flows `CreateObject → EntitySpawn → ItemInstance.Effects` and, live, `PublicUpdatePropertyInt(0x02CE) → ItemRepository.UpdateIntProperty → ItemInstance.Effects`. Any change fires `ItemPropertiesUpdated`, which the bound `UiItemSlot` already re-resolves via `IconComposer.GetIcon(…, effects)`. The compositor mirrors retail `IconData::RenderIcons`: a 2-stage composite where the effect tile (`enum 0x10000005`) supplies a `ReplaceColor(white → effectColor)` tint, never a blit layer.
**Tech Stack:** C# .NET 10, xUnit, `DatReaderWriter` (EnumIDMap/RenderSurface), Silk.NET (GL via `TextureCache`).
**Spec:** [`docs/superpowers/specs/2026-06-17-d2b-stateful-icon-design.md`](../specs/2026-06-17-d2b-stateful-icon-design.md). **Research:** [`docs/research/2026-06-17-stateful-icon-RESOLVED.md`](../../research/2026-06-17-stateful-icon-RESOLVED.md).
**Conventions:** Every commit appends the CLAUDE.md co-author trailer:
`Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>`. Build with `dotnet build`; the tree must be green after every task.
---
### Task 1: Core data model — `ItemInstance.Effects` + `ItemRepository` hooks
**Files:**
- Modify: `src/AcDream.Core/Items/ItemInstance.cs` (add `Effects` field, ~line 138)
- Modify: `src/AcDream.Core/Items/ItemRepository.cs` (`EnrichItem` +param; add `UpdateIntProperty`)
- Test: `tests/AcDream.Core.Tests/Items/ItemRepositoryTests.cs`
- [ ] **Step 1: Write the failing tests**
Add to `ItemRepositoryTests.cs`:
```csharp
[Fact]
public void EnrichItem_carriesEffects()
{
var repo = new ItemRepository();
repo.AddOrUpdate(new ItemInstance { ObjectId = 0x500000AAu });
bool ok = repo.EnrichItem(0x500000AAu, iconId: 0x06001234u, name: "Wand",
type: ItemType.Caster, iconOverlayId: 0, iconUnderlayId: 0, effects: 0x1u);
Assert.True(ok);
Assert.Equal(0x1u, repo.GetItem(0x500000AAu)!.Effects);
}
[Fact]
public void UpdateIntProperty_uiEffects_setsEffectsAndFires()
{
var repo = new ItemRepository();
repo.AddOrUpdate(new ItemInstance { ObjectId = 0x500000ABu });
ItemInstance? fired = null;
repo.ItemPropertiesUpdated += i => fired = i;
bool ok = repo.UpdateIntProperty(0x500000ABu, 18u, value: 0x9); // 18 = UiEffects
Assert.True(ok);
Assert.Equal(0x9u, repo.GetItem(0x500000ABu)!.Effects);
Assert.Equal(0x9, repo.GetItem(0x500000ABu)!.Properties.Ints[18u]);
Assert.NotNull(fired);
}
[Fact]
public void UpdateIntProperty_unknownItem_returnsFalse()
{
var repo = new ItemRepository();
Assert.False(repo.UpdateIntProperty(0xDEADBEEFu, 18u, 1));
}
```
- [ ] **Step 2: Run tests to verify they fail**
Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~ItemRepositoryTests"`
Expected: FAIL — `EnrichItem` has no `effects` param; `UpdateIntProperty`/`Effects` don't exist.
- [ ] **Step 3: Add the `Effects` field**
In `ItemInstance.cs`, after the `IconOverlayId` property (~line 138):
```csharp
/// <summary>
/// UiEffects bitfield (retail PublicWeenieDesc._effects, acclient.h:37183).
/// Drives the icon's effect-overlay recolor (Magical=0x1 … Nether=0x1000).
/// CreateObject-only (weenieFlags 0x80) + live PublicUpdatePropertyInt(0x02CE);
/// appraise never carries it. 0 = no effect.
/// </summary>
public uint Effects { get; set; }
```
- [ ] **Step 4: Add the `effects` param to `EnrichItem`**
In `ItemRepository.cs`, change the `EnrichItem` signature + body:
```csharp
public bool EnrichItem(uint objectId, uint iconId, string name, ItemType type,
uint iconOverlayId = 0, uint iconUnderlayId = 0, uint effects = 0)
{
if (!_items.TryGetValue(objectId, out var item)) return false;
if (iconId != 0) item.IconId = iconId;
if (!string.IsNullOrEmpty(name)) item.Name = name;
if (type != default) item.Type = type;
if (iconOverlayId != 0) item.IconOverlayId = iconOverlayId;
if (iconUnderlayId != 0) item.IconUnderlayId = iconUnderlayId;
// D.5.2: 0 is a meaningful "no effect" state (e.g. a caster out of mana),
// so assign unconditionally — re-composition reflects the CURRENT state.
item.Effects = effects;
ItemPropertiesUpdated?.Invoke(item);
return true;
}
```
- [ ] **Step 5: Add `UpdateIntProperty`**
In `ItemRepository.cs`, add after `UpdateProperties`:
```csharp
/// <summary>PropertyInt.UiEffects (ACE enum value 18) — the icon effect bitfield.</summary>
public const uint UiEffectsPropertyId = 18u;
/// <summary>
/// Apply a single PropertyInt update (from PublicUpdatePropertyInt 0x02CE) to an
/// item: store it in the bundle and, for known typed ints, mirror to the typed
/// field. Today: UiEffects (18) → <see cref="ItemInstance.Effects"/>. Fires
/// ItemPropertiesUpdated so bound widgets re-composite. Extensible hook for future
/// typed PropertyInts (StackSize, Structure, …). False if the item is unknown.
/// </summary>
public bool UpdateIntProperty(uint itemId, uint propertyId, int value)
{
if (!_items.TryGetValue(itemId, out var item)) return false;
item.Properties.Ints[propertyId] = value;
if (propertyId == UiEffectsPropertyId) item.Effects = (uint)value;
ItemPropertiesUpdated?.Invoke(item);
return true;
}
```
- [ ] **Step 6: Run tests to verify they pass**
Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~ItemRepositoryTests"`
Expected: PASS.
- [ ] **Step 7: Commit**
```bash
git add src/AcDream.Core/Items/ItemInstance.cs src/AcDream.Core/Items/ItemRepository.cs tests/AcDream.Core.Tests/Items/ItemRepositoryTests.cs
git commit -m "feat(D.5.2): ItemInstance.Effects + ItemRepository.UpdateIntProperty"
```
---
### Task 2: Capture `UiEffects` from `CreateObject`
**Files:**
- Modify: `src/AcDream.Core.Net/Messages/CreateObject.cs` (record field, capture site, ctor call)
- Test: `tests/AcDream.Core.Net.Tests/Messages/CreateObjectTests.cs`
- [ ] **Step 1: Write the failing tests**
In `CreateObjectTests.cs`, add a `uiEffects` parameter to the builder and write it for the
UiEffects field. Change the builder signature (add `uint uiEffects = 0,` next to `iconId`)
and the UiEffects write line (currently `WriteU32(bytes, 0); // UiEffects u32`):
```csharp
if ((weenieFlags & 0x00000080u) != 0) WriteU32(bytes, uiEffects); // UiEffects u32
```
Then add the tests:
```csharp
[Fact]
public void TryParse_UiEffects_Captured()
{
// weenieFlags 0x80 = UiEffects; value 0x1 = Magical.
byte[] body = BuildMinimalCreateObjectWithWeenieHeader(
guid: 0x50000010u, name: "MagicWand", itemType: (uint)ItemType.Caster,
weenieFlags: 0x80u, uiEffects: 0x1u);
var parsed = CreateObject.TryParse(body);
Assert.NotNull(parsed);
Assert.Equal(0x1u, parsed!.Value.UiEffects);
}
[Fact]
public void TryParse_UiEffectsThenIconOverlay_BothCaptured()
{
// Verifies the cursor still reaches IconOverlay after reading (not skipping) UiEffects.
byte[] body = BuildMinimalCreateObjectWithWeenieHeader(
guid: 0x50000011u, name: "GlowSword", itemType: (uint)ItemType.MeleeWeapon,
weenieFlags: 0x80u | 0x40000000u, uiEffects: 0x4u, iconOverlayId: 0x1ABCu);
var parsed = CreateObject.TryParse(body);
Assert.NotNull(parsed);
Assert.Equal(0x4u, parsed!.Value.UiEffects);
Assert.Equal(0x06001ABCu, parsed.Value.IconOverlayId);
}
[Fact]
public void TryParse_NoUiEffectsBit_LeavesUiEffectsZero()
{
byte[] body = BuildMinimalCreateObjectWithWeenieHeader(
guid: 0x50000012u, name: "PlainRock", itemType: (uint)ItemType.Misc, weenieFlags: 0u);
var parsed = CreateObject.TryParse(body);
Assert.NotNull(parsed);
Assert.Equal(0u, parsed!.Value.UiEffects);
}
```
- [ ] **Step 2: Run tests to verify they fail**
Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj --filter "FullyQualifiedName~CreateObjectTests"`
Expected: FAIL — `Parsed` has no `UiEffects` member.
- [ ] **Step 3: Add the `UiEffects` record field**
In `CreateObject.cs`, in the `Parsed` record, after `uint IconUnderlayId = 0`:
```csharp
uint IconUnderlayId = 0,
// D.5.2 (2026-06-17): UiEffects bitfield (weenieFlags 0x80) — drives the icon's
// effect recolor (Magical=0x1 … Nether=0x1000). The ONLY wire path for the effect
// state (PropertyInt.UiEffects=18 has no [AssessmentProperty] → not in appraise).
// Previously read + discarded at the UiEffects skip. 0 = no effect.
uint UiEffects = 0);
```
- [ ] **Step 4: Capture at the UiEffects site**
In `CreateObject.cs`, declare the local next to `iconOverlayId`/`iconUnderlayId`:
```csharp
uint iconOverlayId = 0;
uint iconUnderlayId = 0;
uint uiEffects = 0;
uint weenieFlags2 = 0;
```
Change the UiEffects skip to a capture:
```csharp
if ((weenieFlags & 0x00000080u) != 0) // UiEffects u32 ← CAPTURE
{
if (body.Length - pos < 4) throw new FormatException("trunc UiEffects");
uiEffects = ReadU32(body, ref pos);
}
```
- [ ] **Step 5: Pass it to the `Parsed` constructor**
In the success-path `return new Parsed(...)`, change the tail:
```csharp
IconId: iconId,
Useability: useability, UseRadius: useRadius,
IconOverlayId: iconOverlayId, IconUnderlayId: iconUnderlayId,
UiEffects: uiEffects);
```
- [ ] **Step 6: Run tests to verify they pass**
Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj --filter "FullyQualifiedName~CreateObjectTests"`
Expected: PASS (all existing CreateObject tests still pass — the builder change is additive).
- [ ] **Step 7: Commit**
```bash
git add src/AcDream.Core.Net/Messages/CreateObject.cs tests/AcDream.Core.Net.Tests/Messages/CreateObjectTests.cs
git commit -m "feat(D.5.2): capture UiEffects from CreateObject weenie header"
```
---
### Task 3: `PublicUpdatePropertyInt (0x02CE)` parser
**Files:**
- Create: `src/AcDream.Core.Net/Messages/PublicUpdatePropertyInt.cs`
- Test: `tests/AcDream.Core.Net.Tests/Messages/PublicUpdatePropertyIntTests.cs`
- [ ] **Step 1: Write the failing tests**
Create `tests/AcDream.Core.Net.Tests/Messages/PublicUpdatePropertyIntTests.cs`:
```csharp
using System.Buffers.Binary;
using AcDream.Core.Net.Messages;
namespace AcDream.Core.Net.Tests.Messages;
public sealed class PublicUpdatePropertyIntTests
{
private static byte[] Build(uint guid, uint property, int value, byte seq = 1, uint opcode = 0x02CEu)
{
var b = new byte[17];
BinaryPrimitives.WriteUInt32LittleEndian(b.AsSpan(0), opcode);
b[4] = seq;
BinaryPrimitives.WriteUInt32LittleEndian(b.AsSpan(5), guid);
BinaryPrimitives.WriteUInt32LittleEndian(b.AsSpan(9), property);
BinaryPrimitives.WriteInt32LittleEndian(b.AsSpan(13), value);
return b;
}
[Fact]
public void TryParse_uiEffectsUpdate_returnsGuidPropValue()
{
var p = PublicUpdatePropertyInt.TryParse(Build(0x50000001u, property: 18u, value: 0x9));
Assert.NotNull(p);
Assert.Equal(0x50000001u, p!.Value.Guid);
Assert.Equal(18u, p.Value.Property);
Assert.Equal(0x9, p.Value.Value);
}
[Fact]
public void TryParse_wrongOpcode_returnsNull()
=> Assert.Null(PublicUpdatePropertyInt.TryParse(Build(1, 18, 1, opcode: 0x02CDu)));
[Fact]
public void TryParse_truncated_returnsNull()
=> Assert.Null(PublicUpdatePropertyInt.TryParse(new byte[16]));
}
```
- [ ] **Step 2: Run tests to verify they fail**
Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj --filter "FullyQualifiedName~PublicUpdatePropertyIntTests"`
Expected: FAIL — `PublicUpdatePropertyInt` does not exist.
- [ ] **Step 3: Create the parser**
Create `src/AcDream.Core.Net/Messages/PublicUpdatePropertyInt.cs`:
```csharp
using System;
using System.Buffers.Binary;
namespace AcDream.Core.Net.Messages;
/// <summary>
/// Inbound <c>PublicUpdatePropertyInt (0x02CE)</c> — the server updates one
/// <c>PropertyInt</c> on a visible object (carries the object guid). Standalone
/// GameMessage, dispatched like <see cref="PrivateUpdateVital"/> / CreateObject.
///
/// <para>
/// The companion <c>PrivateUpdatePropertyInt (0x02CD)</c> targets the player's OWN
/// object (no guid) and is not parsed here — it has no item-icon impact.
/// </para>
///
/// <para>Wire layout (ACE <c>GameMessagePublicUpdatePropertyInt</c>, size hint 17):</para>
/// <code>
/// u32 opcode = 0x02CE
/// u8 sequence // single byte (ByteSequence.NextBytes) — see PrivateUpdateVital
/// u32 guid
/// u32 property // PropertyInt enum; UiEffects = 18
/// i32 value
/// </code>
/// The sequence is parsed-past but not honored (latest-wins; divergence DR-4).
/// </summary>
public static class PublicUpdatePropertyInt
{
public const uint Opcode = 0x02CEu;
public readonly record struct Parsed(uint Guid, uint Property, int Value);
/// <summary>Parse a raw 0x02CE body. Returns null on opcode mismatch / truncation.</summary>
public static Parsed? TryParse(ReadOnlySpan<byte> body)
{
if (body.Length < 17) return null; // 4 + 1 + 4 + 4 + 4
if (BinaryPrimitives.ReadUInt32LittleEndian(body) != Opcode) return null;
int pos = 4;
pos += 1; // sequence byte (not honored)
uint guid = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
uint prop = BinaryPrimitives.ReadUInt32LittleEndian(body[pos..]); pos += 4;
int value = BinaryPrimitives.ReadInt32LittleEndian(body[pos..]);
return new Parsed(guid, prop, value);
}
}
```
- [ ] **Step 4: Run tests to verify they pass**
Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj --filter "FullyQualifiedName~PublicUpdatePropertyIntTests"`
Expected: PASS.
- [ ] **Step 5: Commit**
```bash
git add src/AcDream.Core.Net/Messages/PublicUpdatePropertyInt.cs tests/AcDream.Core.Net.Tests/Messages/PublicUpdatePropertyIntTests.cs
git commit -m "feat(D.5.2): PublicUpdatePropertyInt (0x02CE) parser"
```
---
### Task 4: Thread `UiEffects` through `WorldSession` + route `0x02CE`
**Files:**
- Modify: `src/AcDream.Core.Net/WorldSession.cs` (EntitySpawn field + ctor thread; new event; message-loop branch)
> No unit test: the private message loop needs a live session. The parser is covered by
> Task 3; the event consumption by Tasks 1+8; the end-to-end path by visual verification.
> This matches the existing `PrivateUpdateVital` routing (parser tested, loop not).
- [ ] **Step 1: Add `UiEffects` to the `EntitySpawn` record**
In `WorldSession.cs`, in the `EntitySpawn` record, after `uint IconUnderlayId = 0`:
```csharp
uint IconOverlayId = 0,
uint IconUnderlayId = 0,
// D.5.2 (2026-06-17): UiEffects bitfield (weenieFlags 0x80) — drives the icon's
// effect recolor. CreateObject-only; 0 = no effect.
uint UiEffects = 0);
```
- [ ] **Step 2: Thread it at the `EntitySpawn` construction site**
Find the `new EntitySpawn(... parsed.Value.IconUnderlayId)` construction (the spawn fired from
the CreateObject branch). Change its tail:
```csharp
parsed.Value.IconId,
parsed.Value.IconOverlayId,
parsed.Value.IconUnderlayId,
parsed.Value.UiEffects));
```
- [ ] **Step 3: Declare the live-update event + payload**
In `WorldSession.cs`, near the other event declarations (e.g. after the `StateUpdated`
event ~line 162), add:
```csharp
/// <summary>
/// Payload for <see cref="ObjectIntPropertyUpdated"/>: a single PropertyInt change on
/// a visible object (from PublicUpdatePropertyInt 0x02CE). Subscribers map the
/// property to typed state (e.g. UiEffects → the item's icon effect).
/// </summary>
public readonly record struct ObjectIntPropertyUpdate(uint Guid, uint Property, int Value);
/// <summary>
/// Fires when the session parses a PublicUpdatePropertyInt (0x02CE) — one
/// PropertyInt updated on a visible object. D.5.2 routes UiEffects (18) to the
/// item repository so the icon re-composites live.
/// </summary>
public event Action<ObjectIntPropertyUpdate>? ObjectIntPropertyUpdated;
```
- [ ] **Step 4: Add the message-loop branch**
In the top-level message dispatch (where `op` is the opcode and `body` the message bytes),
add after the `PrivateUpdateVital.CurrentOpcode` branch (~line 905):
```csharp
else if (op == PublicUpdatePropertyInt.Opcode)
{
var p = PublicUpdatePropertyInt.TryParse(body);
if (p is not null)
ObjectIntPropertyUpdated?.Invoke(
new ObjectIntPropertyUpdate(p.Value.Guid, p.Value.Property, p.Value.Value));
}
```
- [ ] **Step 5: Build to verify it compiles**
Run: `dotnet build src/AcDream.Core.Net/AcDream.Core.Net.csproj`
Expected: Build succeeded.
- [ ] **Step 6: Run the Net test suite (regression)**
Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj`
Expected: PASS.
- [ ] **Step 7: Commit**
```bash
git add src/AcDream.Core.Net/WorldSession.cs
git commit -m "feat(D.5.2): thread UiEffects through EntitySpawn + route 0x02CE PublicUpdatePropertyInt"
```
---
### Task 5: `IconComposer.ResolveEffectDid` (effect submap resolve)
**Files:**
- Modify: `src/AcDream.App/UI/IconComposer.cs` (effect-submap fields + `ResolveEffectDid` + `EnsureEffectSubMap`)
- Test: `tests/AcDream.App.Tests/UI/IconComposerTests.cs`
- [ ] **Step 1: Write the failing golden test**
In `IconComposerTests.cs`, add (dat-gated, mirroring `ResolveUnderlayDid_goldenValues_matchDat`):
```csharp
[Fact]
public void ResolveEffectDid_goldenValues_matchDat()
{
var datDir = ResolveDatDir();
if (datDir is null) return; // dats absent (CI) — skip cleanly
using var dats = new DatCollection(datDir, DatAccessType.Read);
var composer = new IconComposer(dats, null!);
// Golden values (live dat, MasterMap 0x25000000 → effect submap 0x25000009;
// index = LowestSetBit(UiEffects)+1, fallback 0x21):
// Magical (0x0001) → idx 1 → 0x060011CA
// Poisoned (0x0002) → idx 2 → 0x060011C6
// BoostHealth (0x0004) → idx 3 → 0x06001B05
// BoostStamina (0x0010) → idx 5 → 0x06001B06
// Nether (0x1000) → idx 13 (absent) → fallback 0x21 → 0x060011C5
// none (0x0000) → idx 0 (zero) → fallback 0x21 → 0x060011C5
Assert.Equal(0x060011CAu, composer.ResolveEffectDid(0x0001u));
Assert.Equal(0x060011C6u, composer.ResolveEffectDid(0x0002u));
Assert.Equal(0x06001B05u, composer.ResolveEffectDid(0x0004u));
Assert.Equal(0x06001B06u, composer.ResolveEffectDid(0x0010u));
Assert.Equal(0x060011C5u, composer.ResolveEffectDid(0x1000u));
Assert.Equal(0x060011C5u, composer.ResolveEffectDid(0x0000u));
}
```
- [ ] **Step 2: Run test to verify it fails**
Run: `dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj --filter "FullyQualifiedName~ResolveEffectDid"`
Expected: FAIL — `ResolveEffectDid` does not exist.
- [ ] **Step 3: Add the effect-submap fields**
In `IconComposer.cs`, after the underlay fields (`_underlayDidByIndex`):
```csharp
// ── effect overlay resolve (EnumIDMap 0x10000005) ────────────────────────
// Portal MasterMap (0x25000000) maps enum 0x10000005 → submap DID (0x25000009).
// Submap maps index → 0x06 RenderSurface DID. index = LSB(effects)+1, fallback 0x21.
// Refs: IconData::RenderIcons 0x0058d180 (effect path); the effect tile is a
// ReplaceColor tint SOURCE, not a blit layer (see RESOLVED doc, divergence DR-1).
private EnumIDMap? _effectSubMap;
private bool _effectResolveTried;
private readonly Dictionary<uint, uint> _effectDidByIndex = new();
```
- [ ] **Step 4: Add `ResolveEffectDid` + `EnsureEffectSubMap`**
In `IconComposer.cs`, after `EnsureUnderlaySubMap`:
```csharp
/// <summary>
/// Resolve the effect-overlay DID for <paramref name="effects"/> via the EnumIDMap
/// 0x10000005 chain. index = LowestSetBit(effects)+1; if the entry is missing/zero,
/// retail falls back to index 0x21 (the solid-black tile). NOTE: the effect path has
/// NO lsb==-1 pre-check (unlike the type underlay), so effects==0 → index 0 → miss →
/// fallback. (Retail IconData::RenderIcons 0x0058d180.)
/// </summary>
internal uint ResolveEffectDid(uint effects)
{
int lsb = effects == 0 ? -1 : BitOperations.TrailingZeroCount(effects);
uint index = (uint)(lsb + 1);
if (_effectDidByIndex.TryGetValue(index, out var cached)) return cached;
EnsureEffectSubMap();
uint did = 0;
if (_effectSubMap is { } sub && sub.ClientEnumToID.TryGetValue(index, out var d)) did = d;
if (did == 0 && _effectSubMap is { } sub2 && sub2.ClientEnumToID.TryGetValue(0x21u, out var fb))
did = fb;
_effectDidByIndex[index] = did;
return did;
}
private void EnsureEffectSubMap()
{
if (_effectResolveTried) return;
_effectResolveTried = true;
uint masterDid = (uint)_dats.Portal.Header.MasterMapId; // = 0x25000000
if (masterDid == 0) return;
if (!_dats.Portal.TryGet<EnumIDMap>(masterDid, out var master)) return;
if (!master.ClientEnumToID.TryGetValue(0x10000005u, out var subDid)) return; // → 0x25000009
if (_dats.Portal.TryGet<EnumIDMap>(subDid, out var sub)) _effectSubMap = sub;
}
```
- [ ] **Step 5: Run test to verify it passes**
Run: `dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj --filter "FullyQualifiedName~ResolveEffectDid"`
Expected: PASS. (If it skips, the dats aren't at `%USERPROFILE%\Documents\Asheron's Call` — set `ACDREAM_DAT_DIR` and re-run.)
- [ ] **Step 6: Commit**
```bash
git add src/AcDream.App/UI/IconComposer.cs tests/AcDream.App.Tests/UI/IconComposerTests.cs
git commit -m "feat(D.5.2): IconComposer.ResolveEffectDid (effect submap 0x10000005)"
```
---
### Task 6: `IconComposer` recolor helpers (`ReplaceColorWhite` + effect color)
**Files:**
- Modify: `src/AcDream.App/UI/IconComposer.cs` (`ReplaceColorWhite`, `TryGetEffectColor`, `TryDecode`)
- Test: `tests/AcDream.App.Tests/UI/IconComposerTests.cs`
- [ ] **Step 1: Write the failing dat-free recolor test**
In `IconComposerTests.cs`, add:
```csharp
[Fact]
public void ReplaceColorWhite_replacesOnlyPureWhiteOpaque()
{
// 2x2: [white-opaque, red-opaque, white-transparent, white-opaque]
var px = new byte[]
{
255,255,255,255, // pure white opaque → replaced
255, 0, 0,255, // red → untouched
255,255,255, 0, // white but alpha 0 → untouched (not 0xFFFFFFFF)
255,255,255,255, // pure white opaque → replaced
};
IconComposer.ReplaceColorWhite(px, 2, 2, (10, 20, 30, 255));
Assert.Equal(new byte[] { 10, 20, 30, 255 }, px[0..4]); // replaced
Assert.Equal(new byte[] { 255, 0, 0, 255 }, px[4..8]); // untouched
Assert.Equal(new byte[] { 255, 255, 255, 0 }, px[8..12]); // untouched
Assert.Equal(new byte[] { 10, 20, 30, 255 }, px[12..16]); // replaced
}
```
- [ ] **Step 2: Run test to verify it fails**
Run: `dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj --filter "FullyQualifiedName~ReplaceColorWhite"`
Expected: FAIL — `ReplaceColorWhite` does not exist.
- [ ] **Step 3: Add `ReplaceColorWhite`**
In `IconComposer.cs`, add (near `Compose`):
```csharp
/// <summary>
/// Retail <c>SurfaceWindow::ReplaceColor</c> (0x00441530) with the icon-composite's
/// fixed source color: replace pixels exactly equal to pure-white-opaque
/// (RGBAColor(1,1,1,1) → 0xFFFFFFFF) with <paramref name="dest"/>. Mutates in place.
/// </summary>
internal static void ReplaceColorWhite(byte[] rgba, int w, int h, (byte r, byte g, byte b, byte a) dest)
{
for (int i = 0; i < w * h; i++)
{
if (rgba[i * 4] == 255 && rgba[i * 4 + 1] == 255 &&
rgba[i * 4 + 2] == 255 && rgba[i * 4 + 3] == 255)
{
rgba[i * 4] = dest.r; rgba[i * 4 + 1] = dest.g;
rgba[i * 4 + 2] = dest.b; rgba[i * 4 + 3] = dest.a;
}
}
}
```
- [ ] **Step 4: Add `TryGetEffectColor` + `TryDecode`**
In `IconComposer.cs`, add the color cache field next to `_effectDidByIndex`:
```csharp
private readonly Dictionary<uint, (byte r, byte g, byte b, byte a)> _effectColorByDid = new();
```
And the methods (after `ResolveEffectDid`):
```csharp
/// <summary>
/// The effect tint color for <paramref name="effects"/>: the effect tile's mean-opaque
/// color (blue=Magical, green=Poisoned, …). The exact retail color byte is a
/// decompiler-ambiguous SurfaceWindow-header read; the tile IS the per-effect color, so
/// its representative color is the faithful equivalent (divergence DR-2). Cached per DID.
/// </summary>
private bool TryGetEffectColor(uint effects, out (byte r, byte g, byte b, byte a) color)
{
color = default;
uint did = ResolveEffectDid(effects);
if (did == 0) return false;
if (_effectColorByDid.TryGetValue(did, out var cached)) { color = cached; return true; }
if (!TryDecode(did, out var d)) return false;
long sr = 0, sg = 0, sb = 0; int n = 0;
for (int i = 0; i < d.Width * d.Height; i++)
{
if (d.Rgba8[i * 4 + 3] == 0) continue;
sr += d.Rgba8[i * 4]; sg += d.Rgba8[i * 4 + 1]; sb += d.Rgba8[i * 4 + 2]; n++;
}
if (n == 0) return false;
var rep = ((byte)(sr / n), (byte)(sg / n), (byte)(sb / n), (byte)255);
_effectColorByDid[did] = rep;
color = rep;
return true;
}
private bool TryDecode(uint renderSurfaceId, out DecodedTexture decoded)
{
decoded = null!;
if (renderSurfaceId == 0) return false;
if (!_dats.Portal.TryGet<RenderSurface>(renderSurfaceId, out var rs) &&
!_dats.HighRes.TryGet<RenderSurface>(renderSurfaceId, out rs))
return false;
decoded = SurfaceDecoder.DecodeRenderSurface(rs, palette: null);
return true;
}
```
> `DecodedTexture` is in `AcDream.Core.Textures` — already imported by `IconComposer.cs`.
- [ ] **Step 5: Run test to verify it passes**
Run: `dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj --filter "FullyQualifiedName~ReplaceColorWhite"`
Expected: PASS.
- [ ] **Step 6: Commit**
```bash
git add src/AcDream.App/UI/IconComposer.cs tests/AcDream.App.Tests/UI/IconComposerTests.cs
git commit -m "feat(D.5.2): IconComposer effect-color + ReplaceColorWhite helpers"
```
---
### Task 7: `IconComposer.GetIcon` 5-arg 2-stage composite + update callers
**Files:**
- Modify: `src/AcDream.App/UI/IconComposer.cs` (`_byTuple` key + `GetIcon` rewrite + class doc)
- Modify: `src/AcDream.App/UI/Layout/ToolbarController.cs` (`_iconIds` Func type + `Populate`)
- Modify: `src/AcDream.App/Rendering/GameWindow.cs` (`iconIds` closure + `OnLiveEntitySpawned` effects)
- Test: `tests/AcDream.App.Tests/UI/IconComposerTests.cs`
> This task changes `GetIcon`'s signature, which breaks both callers; all three files are
> edited together so the tree compiles.
- [ ] **Step 1: Write the failing dat-free composite test**
In `IconComposerTests.cs`, add (exercises the 2-stage compose + recolor without GL/dat via
the static `Compose`/`ReplaceColorWhite` — the GL upload in `GetIcon` needs a real cache):
```csharp
[Fact]
public void TwoStageWithEffect_recolorsWhiteBeforeUnderlay()
{
// drag = base (white pixel) over overlay (none); recolor white→blue; then over
// an opaque tawny underlay. The white pixel must become blue in the final.
var baseIcon = (new byte[] { 255,255,255,255 }, 1, 1); // 1x1 white opaque
var drag = IconComposer.Compose(new[] { baseIcon });
IconComposer.ReplaceColorWhite(drag.rgba, drag.w, drag.h, (0, 0, 255, 255)); // blue
var underlay = (new byte[] { 105, 70, 50, 255 }, 1, 1); // tawny opaque
var final = IconComposer.Compose(new[] { underlay, (drag.rgba, drag.w, drag.h) });
Assert.Equal(new byte[] { 0, 0, 255, 255 }, final.rgba); // blue on top
}
```
- [ ] **Step 2: Run test to verify it fails**
Run: `dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj --filter "FullyQualifiedName~TwoStageWithEffect"`
Expected: FAIL — won't compile yet only if `Compose`/`ReplaceColorWhite` aren't both public/internal; they are (`Compose` public, `ReplaceColorWhite` internal from Task 6), so this test should actually PASS once Task 6 is in. If it passes immediately, that's fine — it locks the recolor-before-underlay ordering. Proceed to Step 3 regardless (the GetIcon rewrite is the real change).
- [ ] **Step 3: Widen the cache key**
In `IconComposer.cs`, change the dictionary field:
```csharp
private readonly Dictionary<(uint, uint, uint, uint, uint), uint> _byTuple = new();
```
- [ ] **Step 4: Rewrite `GetIcon` to 5-arg 2-stage**
Replace the whole `GetIcon` method with:
```csharp
/// <summary>
/// Resolve (and cache) the composited GL texture for an item's icon state.
/// Returns 0 if no base icon. Mirrors retail IconData::RenderIcons (0x0058d180):
/// a DRAG composite (base + custom overlay + effect recolor) blitted over the
/// type-default underlay + custom underlay. The effect tile (enum 0x10000005) is a
/// ReplaceColor tint SOURCE, not a blit layer (DR-1). The 2-stage form is
/// associative-equivalent to a single Compose when effects==0, so D.5.1 visuals are
/// unchanged for non-effect items.
/// </summary>
public uint GetIcon(ItemType itemType, uint iconId, uint underlayId, uint overlayId, uint effects)
{
if (iconId == 0) return 0;
uint typeUnderlayDid = ResolveUnderlayDid(itemType);
var key = (typeUnderlayDid, iconId, underlayId, overlayId, effects);
if (_byTuple.TryGetValue(key, out var tex)) return tex;
// Stage 1 — retail m_pDragIcon: base + custom overlay, then the effect recolor.
var dragLayers = new List<(byte[] rgba, int w, int h)>();
AddLayer(dragLayers, iconId);
AddLayer(dragLayers, overlayId);
(byte[] rgba, int w, int h)? drag = null;
if (dragLayers.Count > 0)
{
var composed = Compose(dragLayers);
// Effect recolor only when an effect bit is set. Retail nominally also runs the
// effects==0 black-fallback recolor; we skip it (DR-3: white→black on every item
// is a likely no-op but a regression risk, pending visual/cdb confirmation).
if (effects != 0 && TryGetEffectColor(effects, out var ec))
ReplaceColorWhite(composed.rgba, composed.w, composed.h, ec);
drag = composed;
}
// Stage 2 — retail m_pIcon: type-default underlay (opaque) + custom underlay + drag.
var layers = new List<(byte[] rgba, int w, int h)>();
AddLayer(layers, typeUnderlayDid);
AddLayer(layers, underlayId);
if (drag is { } d) layers.Add(d);
if (layers.Count == 0) return 0;
var (rgba, w, h) = Compose(layers);
uint handle = _cache.UploadRgba8(rgba, w, h, nearest: true);
_byTuple[key] = handle;
return handle;
}
```
- [ ] **Step 5: Update `ToolbarController` for the new delegate arity**
In `ToolbarController.cs`:
- Change the field type (~line 54):
```csharp
private readonly Func<ItemType, uint, uint, uint, uint, uint> _iconIds; // (itemType, icon, underlay, overlay, effects) → GL tex
```
- Change the constructor parameter type (the `Func<ItemType, uint, uint, uint, uint> iconIds` param):
```csharp
Func<ItemType, uint, uint, uint, uint, uint> iconIds,
```
- Change the `Bind` parameter type to match (same `Func<ItemType, uint, uint, uint, uint, uint> iconIds`).
- In `Populate`, pass `item.Effects`:
```csharp
uint tex = _iconIds(item.Type, item.IconId, item.IconUnderlayId, item.IconOverlayId, item.Effects);
```
- [ ] **Step 6: Update `GameWindow` — closure + spawn enrich**
In `GameWindow.cs`:
- Widen the `iconIds` closure (~line 2005):
```csharp
iconIds: (type, icon, under, over, effects) => iconComposer.GetIcon(type, icon, under, over, effects),
```
- Pass `spawn.UiEffects` in `OnLiveEntitySpawned`'s `EnrichItem` call (~line 2647):
```csharp
Items.EnrichItem(spawn.Guid, spawn.IconId, spawn.Name ?? string.Empty,
(AcDream.Core.Items.ItemType)(spawn.ItemType ?? 0),
spawn.IconOverlayId, spawn.IconUnderlayId, spawn.UiEffects);
```
- [ ] **Step 7: Build + run the App test suite**
Run: `dotnet build src/AcDream.App/AcDream.App.csproj`
Expected: Build succeeded.
Run: `dotnet test tests/AcDream.App.Tests/AcDream.App.Tests.csproj --filter "FullyQualifiedName~IconComposer"`
Expected: PASS.
- [ ] **Step 8: Commit**
```bash
git add src/AcDream.App/UI/IconComposer.cs src/AcDream.App/UI/Layout/ToolbarController.cs src/AcDream.App/Rendering/GameWindow.cs tests/AcDream.App.Tests/UI/IconComposerTests.cs
git commit -m "feat(D.5.2): IconComposer 2-stage effect composite + 5-arg GetIcon"
```
---
### Task 8: Wire the live `0x02CE` update into the item repository
**Files:**
- Modify: `src/AcDream.App/Rendering/GameWindow.cs` (subscribe `ObjectIntPropertyUpdated`, next to `VitalUpdated`)
> No unit test: this is a one-line session-event binding (the same shape as the existing
> `VitalUpdated` binding). `UpdateIntProperty` is unit-tested in Task 1; the end-to-end path
> is the visual-verification acceptance test.
- [ ] **Step 1: Subscribe the event**
In `GameWindow.cs`, next to the `VitalUpdated`/`VitalCurrentUpdated` subscriptions (~line 2630),
add:
```csharp
// D.5.2: live PublicUpdatePropertyInt(0x02CE). Route UiEffects (18) to the item
// repository so a draining/charging item re-composites its icon in real time.
_liveSession.ObjectIntPropertyUpdated += u =>
{
if (u.Property == AcDream.Core.Items.ItemRepository.UiEffectsPropertyId)
Items.UpdateIntProperty(u.Guid, u.Property, u.Value);
};
```
- [ ] **Step 2: Build to verify it compiles**
Run: `dotnet build src/AcDream.App/AcDream.App.csproj`
Expected: Build succeeded.
- [ ] **Step 3: Commit**
```bash
git add src/AcDream.App/Rendering/GameWindow.cs
git commit -m "feat(D.5.2): route live UiEffects updates (0x02CE) to the item icon"
```
---
### Task 9: Bookkeeping — divergence register, roadmap, memory
**Files:**
- Modify: `docs/architecture/retail-divergence-register.md` (retire `IA-16`; add `DR-1..DR-4`)
- Modify: `docs/plans/2026-04-11-roadmap.md` (mark D.5.2 shipped)
- Modify: `claude-memory/project_d2b_retail_ui.md` (D.5.2 entry)
- [ ] **Step 1: Update the divergence register**
In `docs/architecture/retail-divergence-register.md`:
- **Delete the `IA-16` row** (item-icon composite PARTIAL — now complete).
- **Add four rows** (use the table's existing column shape; anchor file:line):
- `DR-1` — effect overlay (enum 0x10000005) is a `ReplaceColor` tint SOURCE, not a blit
layer; this IS faithful retail behavior — do not "fix" it back to a blit. Anchor:
`IconData::RenderIcons` 0x0058d180, `ReplaceColor` 0x00441530; code
`src/AcDream.App/UI/IconComposer.cs` (`GetIcon`).
- `DR-2` — effect tint color = the effect tile's mean-opaque color; the exact retail color
byte (`effectTile + 0xac` reinterpreted as RGBAColor) is decompiler-ambiguous.
Approximation; visual/cdb confirmation pending. Code `IconComposer.TryGetEffectColor`.
- `DR-3` — the `effects==0` black-fallback recolor that retail nominally runs is skipped
(white→black on every item — likely no-op, real regression risk). Code
`IconComposer.GetIcon` (`effects != 0` gate).
- `DR-4` — `PublicUpdatePropertyInt(0x02CE)` sequence not honored (latest-wins). Code
`src/AcDream.Core.Net/Messages/PublicUpdatePropertyInt.cs`.
- [ ] **Step 2: Update the roadmap shipped table**
In `docs/plans/2026-04-11-roadmap.md`, move D.5.2 (stateful item-icon system) into the shipped
section with the commit range and a one-line summary (appraise dropped as no-op; effect recolor
+ live 0x02CE wire-up).
- [ ] **Step 3: Update the D.2b memory digest**
In `claude-memory/project_d2b_retail_ui.md`, append a D.5.2 entry: UiEffects captured from
CreateObject (was discarded) → ItemInstance.Effects → IconComposer 2-stage recolor (effect
tile = ReplaceColor SOURCE, golden submap 0x10000005); live via PublicUpdatePropertyInt 0x02CE;
appraise carries NO icon data (dropped). Link `[[stateful-icon-system-handoff]]` superseded by
the RESOLVED doc.
- [ ] **Step 4: Full build + test sweep**
Run: `dotnet build`
Expected: Build succeeded (no warnings introduced).
Run: `dotnet test`
Expected: All green.
- [ ] **Step 5: Commit**
```bash
git add docs/architecture/retail-divergence-register.md docs/plans/2026-04-11-roadmap.md claude-memory/project_d2b_retail_ui.md
git commit -m "docs(D.5.2): retire IA-16, add DR-1..4, roadmap + memory"
```
---
## Visual verification (acceptance — after all tasks)
Launch against live ACE (per CLAUDE.md "Running the client" recipe), then confirm with the user:
1. A **magical item** pinned to the toolbar shows the effect tint (white highlights take the
effect hue).
2. An item whose **mana drains** updates its icon live (the server's `0x02CE` UiEffects change
re-composites without a relog).
If the tint is wrong/too subtle vs retail, the open lever is `DR-2` (effect color source) — a
cdb trace of `RenderIcons`/`ReplaceColor` on a live retail client resolves the exact byte.
---
## Self-review
- **Spec coverage:** §5.1→T1, §5.2→T2, §5.4→T3, §5.3→T4, §5.5→T1, §5.6→T5+T6+T7,
§5.7→T7, §5.8→T8, §6→T9, §7 tests→T1/T2/T3/T5/T6/T7 + visual. All covered.
- **Placeholders:** none — every code step shows full code; every command shows expected output.
- **Type consistency:** `Func<ItemType,uint,uint,uint,uint,uint>` used identically in
`IconComposer.GetIcon`, `ToolbarController` field/ctor/Bind, and the `GameWindow` closure;
`UiEffectsPropertyId` (18) defined in T1 and referenced in T8; `ObjectIntPropertyUpdate`
record defined in T4 and consumed in T8; `ReplaceColorWhite`/`ResolveEffectDid`/`Compose`
signatures match between definition (T5/T6/T7) and tests.