diff --git a/docs/superpowers/plans/2026-05-12-phase-l2g-slice1.md b/docs/superpowers/plans/2026-05-12-phase-l2g-slice1.md new file mode 100644 index 0000000..2ad4e62 --- /dev/null +++ b/docs/superpowers/plans/2026-05-12-phase-l2g-slice1.md @@ -0,0 +1,899 @@ +# Phase L.2g slice 1 — Dynamic PhysicsState Toggling 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. + +**Spec:** [docs/superpowers/specs/2026-05-12-l2g-dynamic-physicsstate-design.md](../specs/2026-05-12-l2g-dynamic-physicsstate-design.md) (committed in `2c10dd4`). +**Branch:** `claude/gallant-mestorf-3bf2e3` (do all commits here; user merges to main separately). + +**Goal:** Parse inbound `GameMessageSetState (opcode 0xF74B)` and propagate +the new `PhysicsState` value into `ShadowObjectRegistry`'s cached per-entity +record so the existing `CollisionExemption.IsExempt(...)` short-circuit honors +runtime ETHEREAL flips — unblocking the M1 demo's *"open the inn door"* line. + +**Architecture:** One new wire-message parser (`SetState`), one new event on +`WorldSession`, one new mutator method on `ShadowObjectRegistry` +(`UpdatePhysicsState`), one new subscriber in `GameWindow`. **No resolver +changes.** The existing `CollisionExemption.cs` short-circuit (cited at +`acclient_2013_pseudo_c.txt:276782`) already handles ETHEREAL; slice 1 just +feeds it fresh data. + +**Tech Stack:** C# .NET 10, xUnit for tests, BinaryPrimitives for +little-endian reads. Mirror the existing `VectorUpdate.cs` parser pattern. + +**Retail anchor (port reference):** `CPhysicsObj::set_state` at +`docs/research/named-retail/acclient_2013_pseudo_c.txt:283044`. The retail +implementation: `this->state = arg2` (line 283048) plus three side-effect +handlers for the changed-bit set (`0x800` lighting, `0x20` nodraw, `0x4000` +hidden). **Slice 1 ports only the state-store half**; ETHEREAL (`0x4`) is +not in the side-effect set, so the cosmetic handlers are not on the +M1-critical path and stay deferred. + +--- + +## File Structure + +| File | Action | Responsibility | +|---|---|---| +| `src/AcDream.Core.Net/Messages/SetState.cs` | Create | New inbound DTO + `TryParse` for opcode `0xF74B`. Mirrors `VectorUpdate.cs`. | +| `src/AcDream.Core.Net/WorldSession.cs` | Modify | Add `StateUpdated` event + dispatch branch for `op == SetState.Opcode`. | +| `src/AcDream.Core/Physics/ShadowObjectRegistry.cs` | Modify | Add `UpdatePhysicsState(uint, uint)` method that mutates the cached `ShadowEntry.State` in every cell the entity occupies. | +| `src/AcDream.App/Rendering/GameWindow.cs` | Modify | Subscribe to `_liveSession.StateUpdated`, route `(guid, newState)` to `_physicsEngine.ShadowObjects.UpdatePhysicsState(...)`. Extend `[entity-source]` log with `state=` + `flags=` (slice 0.5 freebie). | +| `tests/AcDream.Core.Net.Tests/Messages/SetStateTests.cs` | Create | TryParse byte-level tests (well-formed, truncated, opcode-mismatch). | +| `tests/AcDream.Core.Tests/Physics/ShadowObjectRegistryTests.cs` | Modify | Add `UpdatePhysicsState_FlipsEthereal_NextLookupExempt` test using `CollisionExemption.ShouldSkip`. | + +**No new project references needed** — all files live in existing assemblies. + +--- + +## Task 1: Parser DTO + TryParse for `SetState` (opcode `0xF74B`) + +**Files:** +- Create: `src/AcDream.Core.Net/Messages/SetState.cs` +- Create: `tests/AcDream.Core.Net.Tests/Messages/SetStateTests.cs` + +**Reference template:** `src/AcDream.Core.Net/Messages/VectorUpdate.cs` +(read it before writing — same opcode dispatch convention, same body-length +check shape, same `BinaryPrimitives` style). + +**Wire format** (per +`references/holtburger/crates/holtburger-protocol/src/messages/object/messages/properties.rs:117-122`, +matched by every other acdream parser): + +``` +offset 0 : u32 opcode (= 0xF74B) +offset 4 : u32 guid +offset 8 : u32 physics_state (bitmask; ETHEREAL = 0x4) +offset 12 : u16 instance_sequence +offset 14 : u16 state_sequence +Total: 16 bytes from start of body. +``` + +- [ ] **Step 1.1: Write the failing TryParse tests** + +Create `tests/AcDream.Core.Net.Tests/Messages/SetStateTests.cs` with: + +```csharp +using System; +using System.Buffers.Binary; +using AcDream.Core.Net.Messages; +using Xunit; + +namespace AcDream.Core.Net.Tests.Messages; + +public class SetStateTests +{ + [Fact] + public void TryParse_WellFormedBody_ReturnsParsed() + { + // Build a synthetic SetState body: opcode + guid + state + 2×u16 seq. + var buf = new byte[16]; + BinaryPrimitives.WriteUInt32LittleEndian(buf.AsSpan(0, 4), 0xF74Bu); + BinaryPrimitives.WriteUInt32LittleEndian(buf.AsSpan(4, 4), 0x000F4244u); // door guid + BinaryPrimitives.WriteUInt32LittleEndian(buf.AsSpan(8, 4), 0x00000004u); // ETHEREAL bit + BinaryPrimitives.WriteUInt16LittleEndian(buf.AsSpan(12, 2), (ushort)355); + BinaryPrimitives.WriteUInt16LittleEndian(buf.AsSpan(14, 2), (ushort)42); + + var parsed = SetState.TryParse(buf); + + Assert.NotNull(parsed); + Assert.Equal(0x000F4244u, parsed.Value.Guid); + Assert.Equal(0x00000004u, parsed.Value.PhysicsState); + Assert.Equal((ushort)355, parsed.Value.InstanceSequence); + Assert.Equal((ushort)42, parsed.Value.StateSequence); + } + + [Fact] + public void TryParse_Truncated_ReturnsNull() + { + var buf = new byte[10]; // < 16 bytes + Assert.Null(SetState.TryParse(buf)); + } + + [Fact] + public void TryParse_WrongOpcode_ReturnsNull() + { + var buf = new byte[16]; + BinaryPrimitives.WriteUInt32LittleEndian(buf.AsSpan(0, 4), 0xF74Cu); // UpdateMotion, not SetState + Assert.Null(SetState.TryParse(buf)); + } +} +``` + +- [ ] **Step 1.2: Run tests to verify they fail (RED)** + +Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj --filter "FullyQualifiedName~SetStateTests"` +Expected: Compile error — `SetState` type not defined. + +- [ ] **Step 1.3: Write the parser** + +Create `src/AcDream.Core.Net/Messages/SetState.cs`: + +```csharp +using System; +using System.Buffers.Binary; + +namespace AcDream.Core.Net.Messages; + +/// +/// Inbound SetState GameMessage (opcode 0xF74B). The server +/// broadcasts this whenever a previously-spawned entity's +/// PhysicsState bitmask changes after CreateObject — chiefly +/// when a door opens / closes (server flips ETHEREAL_PS = 0x4) or a +/// spell projectile becomes ethereal post-impact. +/// +/// +/// Wire layout (per +/// references/holtburger/crates/holtburger-protocol/src/messages/object/messages/properties.rs:117-122, +/// matched by every other acdream parser): +/// +/// +/// u32 opcode — 0xF74B +/// u32 objectGuid +/// u32 physicsState — bitmask (acclient.h:2815 / 2819) +/// u16 instanceSequence — stale-packet rejection +/// u16 stateSequence — stale-packet rejection +/// +/// +/// +/// Total body size: 16 bytes from start (opcode + 12-byte payload). +/// +/// +/// +/// Server-side reference: +/// references/ACE/Source/ACE.Server/Network/GameMessages/Messages/GameMessageSetState.cs:8-15 +/// (ACE writes the same field order but appears to use uint for the +/// sequence fields; verified against retail format by hex-dump probe in +/// Task 5). Holtburger has been validated against a retail-format server, +/// so its 12-byte payload is the trusted spec. +/// +/// +public static class SetState +{ + public const uint Opcode = 0xF74Bu; + + public readonly record struct Parsed( + uint Guid, + uint PhysicsState, + ushort InstanceSequence, + ushort StateSequence); + + /// + /// Parse a 0xF74B body. must start with the + /// 4-byte opcode (matches the convention used by VectorUpdate / + /// UpdateMotion / UpdatePosition). Returns null on truncation or + /// opcode mismatch. + /// + public static Parsed? TryParse(ReadOnlySpan body) + { + if (body.Length < 16) return null; + try + { + uint opcode = BinaryPrimitives.ReadUInt32LittleEndian(body.Slice(0, 4)); + if (opcode != Opcode) return null; + + uint guid = BinaryPrimitives.ReadUInt32LittleEndian(body.Slice(4, 4)); + uint state = BinaryPrimitives.ReadUInt32LittleEndian(body.Slice(8, 4)); + ushort instSeq = BinaryPrimitives.ReadUInt16LittleEndian(body.Slice(12, 2)); + ushort stateSeq = BinaryPrimitives.ReadUInt16LittleEndian(body.Slice(14, 2)); + + return new Parsed(guid, state, instSeq, stateSeq); + } + catch + { + return null; + } + } +} +``` + +- [ ] **Step 1.4: Run tests to verify they pass (GREEN)** + +Run: `dotnet test tests/AcDream.Core.Net.Tests/AcDream.Core.Net.Tests.csproj --filter "FullyQualifiedName~SetStateTests"` +Expected: 3 passed. + +- [ ] **Step 1.5: Verify project build still green** + +Run: `dotnet build` +Expected: Build succeeded, 0 errors, 0 new warnings. + +- [ ] **Step 1.6: Commit** + +``` +git add src/AcDream.Core.Net/Messages/SetState.cs tests/AcDream.Core.Net.Tests/Messages/SetStateTests.cs +git commit -m "feat(phys L.2g slice 1): inbound SetState (0xF74B) parser + +DTO + TryParse for the GameMessageSetState wire message. The server +broadcasts this when an already-spawned entity's PhysicsState changes +post-CreateObject — chiefly when a door's Ethereal bit toggles on Use. + +Wire format per holtburger SetStateData (validated against retail-format +servers): u32 opcode + u32 guid + u32 state + u16 instanceSequence + u16 +stateSequence = 16 bytes total. Mirrors the existing VectorUpdate.cs +template. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Task 2: `ShadowObjectRegistry.UpdatePhysicsState(guid, newState)` + +**Files:** +- Modify: `src/AcDream.Core/Physics/ShadowObjectRegistry.cs` (add new method after `UpdatePosition`, before `Deregister`) +- Modify: `tests/AcDream.Core.Tests/Physics/ShadowObjectRegistryTests.cs` (append new test) + +**Design rationale:** `ShadowEntry` is a `readonly record struct` (value type) +stored as copies inside per-cell `List`. Mutation pattern: +find every cell the entity occupies via `_entityToCells[entityId]`, then +replace each in-list copy with `list[i] = list[i] with { State = newState }`. + +**Retail anchor:** `CPhysicsObj::set_state` at +`docs/research/named-retail/acclient_2013_pseudo_c.txt:283044`. Retail +does `this->state = arg2` (line 283048) — direct overwrite. Our cached +state lives in the registry copy, not the entity, so the equivalent is +"overwrite every shadow copy." + +- [ ] **Step 2.1: Write the failing test** + +Append to `tests/AcDream.Core.Tests/Physics/ShadowObjectRegistryTests.cs` +(top-of-file using directives already have `AcDream.Core.Physics` + xUnit): + +```csharp + // ----------------------------------------------------------------------- + // UpdatePhysicsState — L.2g slice 1 (doors flip ETHEREAL post-spawn) + // ----------------------------------------------------------------------- + + [Fact] + public void UpdatePhysicsState_FlipsEthereal_NextLookupSeesNewBits() + { + // Register a door-like entity with State=0 (closed = solid). + var reg = new ShadowObjectRegistry(); + const uint doorId = 0x000F4244u; + reg.Register(doorId, 0x020019FFu, new Vector3(12f, 12f, 50f), + Quaternion.Identity, 1f, OffX, OffY, LbId, + state: 0u, flags: EntityCollisionFlags.None); + + // Sanity: cached state starts at 0 (no ETHEREAL). + var before = reg.AllEntriesForDebug().Single(e => e.EntityId == doorId); + Assert.Equal(0u, before.State); + + // Flip ETHEREAL_PS (0x4) — the server's "door is now open" message. + reg.UpdatePhysicsState(doorId, 0x00000004u); + + // Cached state should now show the new bit. + var after = reg.AllEntriesForDebug().Single(e => e.EntityId == doorId); + Assert.Equal(0x00000004u, after.State); + } + + [Fact] + public void UpdatePhysicsState_UnregisteredEntity_IsNoOp() + { + var reg = new ShadowObjectRegistry(); + // No entity registered. Should not throw. + reg.UpdatePhysicsState(0xDEADBEEFu, 0x00000004u); + Assert.Equal(0, reg.TotalRegistered); + } + + [Fact] + public void UpdatePhysicsState_EntitySpanningMultipleCells_AllCellsUpdated() + { + // Entity at (24,12) with radius=2 spans cells (0,0) and (1,0). + var reg = new ShadowObjectRegistry(); + reg.Register(99u, 0x01000099u, new Vector3(24f, 12f, 50f), + Quaternion.Identity, 2f, OffX, OffY, LbId, + state: 0u); + + reg.UpdatePhysicsState(99u, 0x00000004u); + + uint cellA = LbId | 1u; // cx=0 + uint cellB = LbId | (1u*8 + 0 + 1); // cx=1 + var inA = reg.GetObjectsInCell(cellA).Single(e => e.EntityId == 99u); + var inB = reg.GetObjectsInCell(cellB).Single(e => e.EntityId == 99u); + Assert.Equal(0x00000004u, inA.State); + Assert.Equal(0x00000004u, inB.State); + } +``` + +You may need a `using System.Linq;` at the top of the test file. Add it if +not already present. + +- [ ] **Step 2.2: Run tests to verify they fail (RED)** + +Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~UpdatePhysicsState"` +Expected: Compile error — `UpdatePhysicsState` method not defined. + +- [ ] **Step 2.3: Implement `UpdatePhysicsState`** + +Insert into `src/AcDream.Core/Physics/ShadowObjectRegistry.cs` after the +`UpdatePosition` method (around line 127, before the `Deregister` summary +comment): + +```csharp + /// + /// Update the cached bits for an + /// already-registered entity. Called by the inbound + /// SetState (0xF74B) dispatcher when the server broadcasts a + /// post-spawn PhysicsState change — chiefly doors flipping + /// ETHEREAL_PS = 0x4 on Use, so the + /// short-circuit can honor + /// the new state on the next resolve. + /// + /// + /// Retail equivalent: CPhysicsObj::set_state at + /// docs/research/named-retail/acclient_2013_pseudo_c.txt:283044 + /// — direct write `this->state = arg2`. Retail also fires side-effect + /// handlers for the 0x800 (lighting), 0x20 (nodraw), 0x4000 (hidden) + /// changed bits; ETHEREAL (0x4) doesn't trigger any of them, so slice 1 + /// scopes to the bare state-write. + /// + /// + /// + /// Implementation: is a value-type record + /// copied into per-cell lists, so we rewrite the copy in each cell the + /// entity occupies. Unregistered entities are a no-op (callers don't + /// have to gate). + /// + /// + public void UpdatePhysicsState(uint entityId, uint newState) + { + if (!_entityToCells.TryGetValue(entityId, out var cellIds)) + return; // not registered — no-op + + foreach (var cellId in cellIds) + { + if (!_cells.TryGetValue(cellId, out var list)) continue; + for (int i = 0; i < list.Count; i++) + { + if (list[i].EntityId == entityId) + list[i] = list[i] with { State = newState }; + } + } + } +``` + +- [ ] **Step 2.4: Run tests to verify they pass (GREEN)** + +Run: `dotnet test tests/AcDream.Core.Tests/AcDream.Core.Tests.csproj --filter "FullyQualifiedName~UpdatePhysicsState"` +Expected: 3 passed. + +- [ ] **Step 2.5: Verify full test suite still green (no regressions)** + +Run: `dotnet test` +Expected: All previously-passing tests still pass. **Note:** ~8 pre-existing +failures may be in the baseline (see `docs/research/2026-05-13-l2d-slice1-shipped-handoff.md` +"Open concerns"); ensure the count does not increase. Stash + rerun to +confirm if uncertain: `git stash && dotnet test 2>&1 | findstr Failed` then +`git stash pop`. + +- [ ] **Step 2.6: Commit** + +``` +git add src/AcDream.Core/Physics/ShadowObjectRegistry.cs tests/AcDream.Core.Tests/Physics/ShadowObjectRegistryTests.cs +git commit -m "feat(phys L.2g slice 1): ShadowObjectRegistry.UpdatePhysicsState + +New mutator that overwrites cached PhysicsState bits on every shadow copy +of the named entity. The existing CollisionExemption.ShouldSkip(...) check +(acclient_2013_pseudo_c.txt:276782) reads the same cached field, so a +post-spawn ETHEREAL flip is now honored on the next resolver tick without +any resolver-path change. + +Retail anchor: CPhysicsObj::set_state at acclient_2013_pseudo_c.txt:283044. +Slice 1 scopes to the bare state-write — retail's cosmetic side-effect +handlers (0x800 lighting, 0x20 nodraw, 0x4000 hidden) don't fire for the +ETHEREAL bit and stay deferred. + +Three TDD tests cover: ETHEREAL flip from 0->0x4; unregistered-entity +no-op; entity spanning multiple cells gets all copies updated. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Task 3: Wire `0xF74B` into `WorldSession` dispatcher + new event + +**Files:** +- Modify: `src/AcDream.Core.Net/WorldSession.cs` (one new event declaration near the existing `VectorUpdated`/`MotionUpdated` events; one new `else if` branch in the inbound dispatcher near `op == VectorUpdate.Opcode`) + +**Reference pattern:** Read the existing `VectorUpdate.Opcode` branch first +(it's at WorldSession.cs:739–752). Copy its shape exactly. + +- [ ] **Step 3.1: Add the public event declaration** + +Find the existing `public event Action<...>? VectorUpdated;` declaration +in `WorldSession.cs` (near line 119, in the events region). Add a sibling: + +```csharp + /// + /// Fires when the server broadcasts a SetState (0xF74B) game + /// message — a previously-spawned entity's PhysicsState + /// bitmask changed post-CreateObject. Chiefly doors flipping + /// ETHEREAL_PS = 0x4 on Use (see ACE + /// WorldObjects/Door.cs:127, WorldObject.cs:640-660). + /// Subscribers route the new state into + /// so the + /// existing collision-exemption short-circuit honors the flip on the + /// next resolver tick. + /// + public event Action? StateUpdated; +``` + +Place it immediately after the existing `VectorUpdated` event for grep- +findability. + +- [ ] **Step 3.2: Add the dispatcher branch** + +In the inbound game-message dispatcher (the chain of `else if (op == X.Opcode)` +branches in the same file), add this branch immediately after the +`VectorUpdate.Opcode` branch: + +```csharp + else if (op == SetState.Opcode) + { + // L.2g slice 1 (2026-05-12): server broadcasts SetState + // (0xF74B) when an entity's PhysicsState changes + // post-spawn — chiefly doors flipping ETHEREAL on Use. + // Holtburger validated wire format = 16 bytes (opcode + + // guid + state + 2×u16 sequence). ACE + // GameMessageSetState.cs writes the same field order + // but appears to use u32 for the sequences; Task 5's + // hex-dump probe settles the actual byte count. + var parsed = SetState.TryParse(body); + if (parsed is not null) + StateUpdated?.Invoke(parsed.Value); + } +``` + +The `using AcDream.Core.Net.Messages;` directive should already be at the +top of WorldSession.cs (it's used by every existing parser). Confirm, +don't add a duplicate. + +- [ ] **Step 3.3: Verify build still green** + +Run: `dotnet build` +Expected: Build succeeded, 0 errors. + +- [ ] **Step 3.4: Commit** + +``` +git add src/AcDream.Core.Net/WorldSession.cs +git commit -m "feat(phys L.2g slice 1): WorldSession dispatches SetState (0xF74B) + +New StateUpdated event + dispatcher branch routes inbound SetState +messages to subscribers. Mirrors the existing VectorUpdated / +MotionUpdated event pattern. GameWindow will subscribe in the next +commit and feed the parsed (guid, newState) pair to +ShadowObjectRegistry.UpdatePhysicsState. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Task 4: Subscribe in `GameWindow` and feed `ShadowObjectRegistry` + +**Files:** +- Modify: `src/AcDream.App/Rendering/GameWindow.cs` (one new subscription line + one new handler method) + +This is the final wiring step. After this commit, the server's "door opened" +SetState is end-to-end honored by the collision system. + +- [ ] **Step 4.1: Add the subscription** + +Find the block in `GameWindow.cs` where `_liveSession.MotionUpdated += +OnLiveMotionUpdated;` and `_liveSession.PositionUpdated += +OnLivePositionUpdated;` are wired (around line 1791). Add: + +```csharp + _liveSession.StateUpdated += OnLiveStateUpdated; +``` + +Place it after `_liveSession.VectorUpdated += OnLiveVectorUpdated;` so the +event-subscription order is co-located with its peers. + +- [ ] **Step 4.2: Add the handler method** + +Find the existing `OnLiveVectorUpdated` method body in the same file +(grep `private void OnLiveVectorUpdated`). Add a sibling handler +immediately after it: + +```csharp + /// + /// L.2g slice 1: inbound SetState (0xF74B) handler. Propagates the + /// new PhysicsState bits into ShadowObjectRegistry so the + /// existing check honors + /// the flip on the next resolver tick. Chiefly doors: + /// server flips ETHEREAL_PS = 0x4 on Use, the door's + /// cylinder collision stops blocking the threshold. + /// + private void OnLiveStateUpdated(AcDream.Core.Net.Messages.SetState.Parsed parsed) + { + _physicsEngine.ShadowObjects.UpdatePhysicsState(parsed.Guid, parsed.PhysicsState); + + if (AcDream.Core.Physics.PhysicsDiagnostics.ProbeBuildingEnabled) + Console.WriteLine(System.FormattableString.Invariant( + $"[setstate] guid=0x{parsed.Guid:X8} state=0x{parsed.PhysicsState:X8} instSeq={parsed.InstanceSequence} stateSeq={parsed.StateSequence}")); + } +``` + +- [ ] **Step 4.3: Verify build still green** + +Run: `dotnet build` +Expected: Build succeeded, 0 errors. + +- [ ] **Step 4.4: Smoke-test that no regression breaks the launch path** + +Run a quick non-interactive smoke (do NOT do the full visual test yet — +that's Task 7): + +```powershell +$env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call" +$env:ACDREAM_LIVE = "0" # offline; just verify the binary starts +dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | + Select-String -Pattern "Exception|FATAL" | + Select-Object -First 5 +``` + +Then kill the process. Expected: no startup exception, no FATAL. If +anything blows up, the new handler subscription or the registry mutator +broke something in the live-session attach path. + +- [ ] **Step 4.5: Commit** + +``` +git add src/AcDream.App/Rendering/GameWindow.cs +git commit -m "feat(phys L.2g slice 1): GameWindow routes SetState into registry + +End-to-end wiring: WorldSession.StateUpdated fires -> GameWindow +OnLiveStateUpdated -> ShadowObjectRegistry.UpdatePhysicsState -> next +resolver tick sees the updated ETHEREAL bit and CollisionExemption +short-circuits the door cylinder. After this commit the M1 'open the +inn door' scenario is unblocked at the code-path level; visual +verification follows in slice 1's manual test (Task 7). + +The handler also emits a [setstate] diagnostic line when +ACDREAM_PROBE_BUILDING is enabled — gives a greppable trail when the +visual test runs. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Task 5: Hex-dump probe for first SetState payload (wire-byte verification) + +**Files:** +- Modify: `src/AcDream.Core.Net/WorldSession.cs` (extend the existing `else if (op == SetState.Opcode)` branch added in Task 3) + +**Why:** ACE's `GameMessageSetState.cs:13-14` writes `Sequences.GetCurrentSequence(...)` ++ `Sequences.GetNextSequence(...)` as `uint` calls — potentially 4 bytes +each (16-byte total payload) instead of holtburger's 12 bytes. We default to +holtburger's spec because it's been validated against live retail-format +servers, but we want one-shot evidence on real wire bytes before declaring +slice 1 done. + +The probe is gated on `ACDREAM_PROBE_BUILDING` (existing env var from +L.2d slice 1) and fires once per SetState message; the body bytes are +short enough that this is cheap. + +- [ ] **Step 5.1: Extend the dispatcher branch with a hex-dump** + +Update the `else if (op == SetState.Opcode)` branch from Task 3 to: + +```csharp + else if (op == SetState.Opcode) + { + // L.2g slice 1 (2026-05-12) — see Task 3 above for the + // event-routing intent. The probe-gated hex-dump here + // captures the wire bytes one-shot per session so we can + // confirm holtburger's 12-byte payload format (vs ACE's + // GameMessageSetState.cs claim of u32 sequences = 16 + // bytes) before declaring slice 1 done. + if (AcDream.Core.Physics.PhysicsDiagnostics.ProbeBuildingEnabled + && !_setStateHexDumped) + { + _setStateHexDumped = true; + var hex = string.Join(" ", body.Take(Math.Min(body.Length, 32)) + .Select(b => b.ToString("X2"))); + Console.WriteLine($"[setstate-hex] body.len={body.Length} first-{Math.Min(body.Length, 32)}-bytes: {hex}"); + } + + var parsed = SetState.TryParse(body); + if (parsed is not null) + StateUpdated?.Invoke(parsed.Value); + } +``` + +Add the one-shot flag field near the top of the `WorldSession` class +(group with other `_dump*Enabled` flags — grep `private bool _` to find +the cluster): + +```csharp + /// L.2g slice 1: one-shot guard so the [setstate-hex] probe + /// emits the first SetState's body bytes only, not 5–10/sec. + private bool _setStateHexDumped; +``` + +Note: the `body.Take(...)` requires `using System.Linq;` — already present. + +- [ ] **Step 5.2: Verify build still green** + +Run: `dotnet build` +Expected: Build succeeded, 0 errors. + +- [ ] **Step 5.3: Commit** + +``` +git add src/AcDream.Core.Net/WorldSession.cs +git commit -m "feat(phys L.2g slice 1): one-shot hex-dump probe for SetState payload + +Probe-gated diagnostic (ACDREAM_PROBE_BUILDING) emits the first inbound +SetState message's body bytes so we can confirm holtburger's 12-byte +payload format vs ACE's GameMessageSetState.cs claim of u32 sequences +(16-byte payload). One-shot via _setStateHexDumped — won't flood the +log when doors auto-close every 30s. + +If the hex-dump shows body.len > 16, the parser's body-length gate at +SetState.cs needs widening (and the seq-field reads shifted accordingly). +If it shows 16, we ship as-is. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Task 6: Slice 0.5 — extend `[entity-source]` log with `state` + `flags` + +**Files:** +- Modify: `src/AcDream.App/Rendering/GameWindow.cs` (extend the existing `[entity-source]` log line — there are 2 sites; modify both for consistency) + +**Why:** The L.2d slice 1 handoff flagged this as a useful "slice 1.6" +addendum. It's 5 LOC, fold-into-slice-1-freebie. Makes ETHEREAL flips +greppable end-to-end: spawn -> registry update -> resolver effect. + +- [ ] **Step 6.1: Find both `[entity-source]` log sites** + +Grep `[entity-source]` in `src/AcDream.App/Rendering/GameWindow.cs` and +note the two `Console.WriteLine` calls (one is around line 2978 from the +RegisterLiveEntityForCollision path; the other should be in the +landblock-baked static registration path — grep confirms by file). Both +need the same suffix addition. + +- [ ] **Step 6.2: Extend both log lines** + +For each `[entity-source]` line, append `state=0x{state:X8} flags={flags}` +to the format string. Example transformation: + +Before: +```csharp +Console.WriteLine(System.FormattableString.Invariant( + $"[entity-source] id=0x{entity.Id:X8} entityId=0x{entity.Id:X8} src=0x{entity.SourceGfxObjOrSetupId:X8} gfxObj=0x{entity.SourceGfxObjOrSetupId:X8} lb=0x{spawn.Position.Value.LandblockId:X8} type=Cylinder note=server-spawn-root")); +``` + +After (note: the local variables `state` and `flags` should already be +in scope at both sites — they're computed just before the +`ShadowObjects.Register(...)` call; grep upward 5–10 lines from each log +site to confirm): + +```csharp +Console.WriteLine(System.FormattableString.Invariant( + $"[entity-source] id=0x{entity.Id:X8} entityId=0x{entity.Id:X8} src=0x{entity.SourceGfxObjOrSetupId:X8} gfxObj=0x{entity.SourceGfxObjOrSetupId:X8} lb=0x{spawn.Position.Value.LandblockId:X8} type=Cylinder note=server-spawn-root state=0x{state:X8} flags={flags}")); +``` + +If the `state` or `flags` variables are scoped differently at one site +(e.g. one site is for landblock-baked statics that always have state=0), +substitute the literal `0u` or `EntityCollisionFlags.None` and add a +comment noting the static-default. Keep the field names identical at both +sites so a single regex `state=0x([0-9A-F]+)` catches every entry. + +- [ ] **Step 6.3: Verify build still green** + +Run: `dotnet build` +Expected: Build succeeded, 0 errors. + +- [ ] **Step 6.4: Commit** + +``` +git add src/AcDream.App/Rendering/GameWindow.cs +git commit -m "feat(phys L.2g slice 1): extend [entity-source] log with state + flags + +5-LOC freebie folded into L.2g slice 1: the [entity-source] probe now +emits the PhysicsState bits + EntityCollisionFlags decoded at +registration. Combined with the new [setstate] handler log line, this +makes door open/close events fully greppable end-to-end: + spawn -> [entity-source] guid=... state=0x00000000 ... + Use -> [setstate] guid=... state=0x00000004 ... + close -> [setstate] guid=... state=0x00000000 ... + +Resolves the 'slice 1.6' suggestion from +docs/research/2026-05-13-l2d-slice1-shipped-handoff.md. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Task 7: Visual verification at Holtburg inn doorway + +**Files:** None — this is a user-driven test. Document the recipe; report +results in the handoff doc (Task 8). + +**Acceptance:** +1. Walk acdream `+Acdream` into the Holtburg inn doorway. **Expected: blocked at threshold.** +2. Click the door (Use action). **Expected: door swings open; `[setstate]` log line emits with `state=0x00000004`; walk through clears.** +3. Wait ~30 seconds. **Expected: door auto-closes; `[setstate]` log line emits with `state=0x00000000`; threshold blocks again.** +4. Inspect the `[setstate-hex]` line emitted on the first SetState — confirm `body.len=16`. If it's 20 instead, slice 1 has a bug to file as 1b. + +- [ ] **Step 7.1: Launch the client with probes enabled** + +Wait ~5 seconds since the last close (per CLAUDE.md's logout-before-reconnect +note) then: + +```powershell +$env:ACDREAM_DAT_DIR = "$env:USERPROFILE\Documents\Asheron's Call" +$env:ACDREAM_LIVE = "1" +$env:ACDREAM_TEST_HOST = "127.0.0.1" +$env:ACDREAM_TEST_PORT = "9000" +$env:ACDREAM_TEST_USER = "testaccount" +$env:ACDREAM_TEST_PASS = "testpassword" +$env:ACDREAM_DEVTOOLS = "1" +$env:ACDREAM_PROBE_BUILDING = "1" +$env:ACDREAM_PROBE_RESOLVE = "1" +dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 | + Tee-Object -FilePath "launch-l2g-slice1.log" +``` + +- [ ] **Step 7.2: Manually perform the four-step scenario** + +(User-driven. See Acceptance list above.) + +- [ ] **Step 7.3: Inspect the log for the four expected lines** + +After closing the client window: + +```powershell +Select-String -Path launch-l2g-slice1.log -Pattern "setstate-hex|setstate.*guid|entity-source.*Door" +``` + +Expected matches: +- One `[setstate-hex] body.len=16 first-16-bytes: 4B F7 ...` line. +- One `[entity-source] ... name=Door ... state=0x00000000 ...` (or similar). +- A `[setstate] guid=0x000F.... state=0x00000004 ...` after the Use click. +- A `[setstate] guid=0x000F.... state=0x00000000 ...` ~30s after the previous. + +- [ ] **Step 7.4: Decide ship-or-fix** + +Three outcomes: +- **All four log lines match + door scenario works visually:** slice 1 ships. Proceed to Task 8. +- **Log lines correct but visual scenario fails (door visually opens but player still blocked):** the resolver is reading stale state from somewhere we haven't found. Stop and file a "slice 1b — find the second cache layer" note. +- **`[setstate-hex] body.len=20`:** ACE's u32 sequence claim is real. Widen `SetState.cs` body-length gate (`16` -> `20`) and shift sequence reads to `body.Slice(12, 4)` + `body.Slice(16, 4)` (read as `uint`, cast to `ushort` if values are small — high bits will be zero per ACE's `Sequences` design). Re-run from Task 7.1. + +--- + +## Task 8: Ship handoff doc + roadmap update + +**Files:** +- Create: `docs/research/2026-05-XX-l2g-slice1-shipped-handoff.md` (replace `XX` with the actual ship date) +- Modify: `CLAUDE.md` (replace the "the natural next step is the L.2g slice 1 implementation" paragraph with a "Phase L.2g slice 1 shipped " paragraph mirroring the L.2a paragraph style) +- Modify: `docs/plans/2026-04-29-movement-collision-conformance.md` (under the L.2g section, add a "Current shipped slice" subsection noting slice 1 + its commit hashes) + +- [ ] **Step 8.1: Write the ship handoff doc** + +Use the existing handoff at +`docs/research/2026-05-13-l2d-slice1-shipped-handoff.md` as a template. The +new doc should cover: + +- TL;DR: what landed, did the visual test pass. +- What shipped (commit hash + subject per commit from Tasks 1–6). +- What the visual test showed (the four log-line samples from Task 7.3). +- Wire-byte width resolution (12-byte vs 16-byte — whichever the hex-dump + showed). +- Side findings (anything noticed during visual test — door animation + flickers, audio not playing, etc — file under "deferred"). +- Next-session candidates (L.2g slice 2 animation confirmation, deferred UX + polish, OR pick from CLAUDE.md's now-revised "Next phase candidates" + list). + +- [ ] **Step 8.2: Update CLAUDE.md** + +Find the "Currently in Phase L.2 (Movement & Collision Conformance)" +paragraph. Replace its "the natural next step is the L.2g slice 1 +implementation" sentence with "L.2g slice 1 shipped — doors honor +ETHEREAL flips end-to-end; visual-verified at Holtburg inn doorway." Add +a "**Phase L.2g slice 1 shipped .**" descriptive paragraph after +the L.2a paragraph (mirror the L.2a paragraph's depth). + +In the "**Next phase candidates**" list, demote the current L.2g item +out and pick whichever is the next sensible candidate (likely L.2g slice 2 +animation confirmation OR a non-L.2 visual-fidelity item — depends on what +the visual test in Task 7 showed). + +- [ ] **Step 8.3: Update the L.2 plan-of-record** + +In `docs/plans/2026-04-29-movement-collision-conformance.md`, under the +L.2g section, add a "Current shipped slice ():" subsection +listing the slice 1 commit hashes + their subjects (use git log to fill +in). Mirror the L.2c "Current shipped slice (2026-04-30):" subsection +style. + +- [ ] **Step 8.4: Commit** + +``` +git add CLAUDE.md docs/plans/2026-04-29-movement-collision-conformance.md docs/research/2026-05-XX-l2g-slice1-shipped-handoff.md +git commit -m "docs(phys L.2g): slice 1 shipped handoff + plan-of-record + CLAUDE.md + +Slice 1 visual-verified at Holtburg inn doorway: walking into closed door +is blocked, Use opens it, walk-through clears, auto-close re-blocks at 30s. +Wire-byte width settled (see handoff doc). + +L.2g slice 2 (animation confirmation) becomes the next candidate IF the +visual test showed door animation not playing; otherwise slice 2 is a +verify-only no-op and we move to the next phase candidate. + +Co-Authored-By: Claude Opus 4.7 (1M context) " +``` + +--- + +## Plan self-review + +**1. Spec coverage check:** + +| Spec section | Task | +|---|---| +| Slice 1 — parse SetState (0xF74B) | Tasks 1 + 3 + 5 | +| Slice 1 — plumb new state into ShadowObjectRegistry | Tasks 2 + 4 | +| Slice 1 — visual verification at Holtburg | Task 7 | +| Slice 0.5 — extend [entity-source] log with state + flags | Task 6 | +| Open Q1 — wire-byte width | Task 5 (hex-dump probe) + Task 7.4 (decision branch) | +| Open Q2 — UpdateMotion drives non-creature entities (door swing animation) | **Deferred to slice 2** (per the spec — animation is verify-only) | +| Open Q3 — SetState delivered to the player who triggered Use | Task 7 visual test verifies (covered implicitly by the four-step scenario) | +| Acceptance — design spec, plan-of-record, milestones, CLAUDE.md all reference L.2g | Already done in `2c10dd4`; Task 8 closes the loop with the slice 1 ship handoff | +| Named retail citation in slice 1 code | Task 2.3 cites `acclient_2013_pseudo_c.txt:283044`; Task 1.3 cites the holtburger struct | + +**2. Placeholder scan:** No `TBD`, `TODO`, "fill in later." `` in +Task 8 is a deliberate placeholder for the engineer to fill in at ship +time — flagged as such in the handoff doc template, not a plan-writing +oversight. The `Task 8.1` doc filename uses `2026-05-XX` for the same +reason. + +**3. Type consistency:** `SetState.Parsed(Guid, PhysicsState, InstanceSequence, StateSequence)` +used consistently in Tasks 1, 3, 4, 5. `UpdatePhysicsState(uint entityId, uint newState)` +signature consistent in Tasks 2 + 4. `ShadowEntry.State` matches the +existing struct definition in `ShadowObjectRegistry.cs:262-280`. + +**4. Risk surface:** All changes are additive. No resolver edits. No +broadphase edits. No retail-port semantics changes. If anything goes +wrong, single-commit revert per task. + +--- + +## Execution + +Plan complete. Two execution options when ready: + +**1. Subagent-Driven (recommended)** — Dispatch a fresh Sonnet subagent per task (Task 1 alone, Tasks 2 + 3 together, Task 4 + 5 + 6 together, Task 7 user-driven, Task 8 docs). Review between dispatches. Each subagent stays bounded to one commit's worth of changes; parent context stays clean. + +**2. Inline Execution** — Drive all tasks in this session using executing-plans. Faster end-to-end but consumes ~4× more parent context. + +Total scope estimate: ~6 commits over ~30–60 minutes of work + Task 7 visual test (~10 minutes when ACE + retail client are already running).