acdream/docs/research/2026-05-08-phase-n4-week4-handoff.md

# Phase N.4 Week 4 handoff — full draw dispatcher + visual verification + ship

**Use this whole document as the prompt** when handing off to a fresh
agent. Everything they need to pick up cold is below.

---

## Background you'll need

You're working in `acdream`, a from-scratch C# .NET 10 reimplementation
of Asheron's Call's retail client. The project's house rule (in
`CLAUDE.md`) is **the code is modern, the behavior is retail**.

acdream is in the middle of Phase N.4 — the rendering pipeline
foundation migration to WorldBuilder's `ObjectMeshManager` +
`TextureAtlasManager`. **Three of the four planned weeks have shipped
this session (2026-05-08)**:

- Week 1 (commits up through `c49c6ed`): foundation types — feature
  flag, surface metadata side-table, mesh-extraction + setup-flatten
  conformance tests, `WbMeshAdapter` constructed against the real WB
  pipeline.
- Week 2 (commits up through `36f7a60`): streaming integration —
  `LandblockSpawnAdapter` routes atlas-tier (procedural / `ServerGuid==0`)
  GfxObjs to WB's ref-count lifecycle. `WbMeshAdapter.Tick()` drains
  the WB pipeline's main-thread queues per frame (fixes a real memory
  leak).
- Week 3 (commits up through `d30fcb2`): per-instance tier hookup —
  `AnimatedEntityState` holds per-server-spawned-entity overrides;
  `EntitySpawnAdapter` routes server-spawned entities through the
  existing `TextureCache.GetOrUploadWithPaletteOverride` decode path.

**Current state at `main`:** build green, **947 tests pass**, 8
pre-existing failures only (unchanged from pre-N.4 main). Default-off
behavior is byte-identical to pre-N.4 main; flag-on (`ACDREAM_USE_WB_FOUNDATION=1`)
runs both rendering pipelines in parallel — WB silently prepares
content, but nothing is yet drawn through it.

**Read first:**

- [docs/superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md](../superpowers/plans/2026-05-08-phase-n4-rendering-foundation.md) —
  the **living-document** plan. Top of file has a Progress table
  showing Tasks 1-21 ✅ shipped with commit SHAs. Adjustments 1-5
  document architectural surprises caught during execution. **Read the
  Adjustments before writing any Task 22 code** — they explain why the
  current architecture is what it is.
- [docs/superpowers/specs/2026-05-08-phase-n4-rendering-foundation-design.md](../superpowers/specs/2026-05-08-phase-n4-rendering-foundation-design.md) —
  the design spec. Architecture / two-tier split / animation handling /
  data-flow diagrams. Strategic source of truth for "how the pieces
  fit together."
- [CLAUDE.md](../../CLAUDE.md) — project-wide rules. The "Currently in
  flight" section near the top points at the plan.

## What Week 4 is

Seven tasks (22-28). **Task 22 alone is the biggest single task in the
entire 28-task plan** — it's the moment we flip from "WB is silently
preparing content" to "WB is drawing content to your screen."

The remaining six tasks are smaller: surface-metadata side-table
population, sky-pass preservation check, micro-tests round-out, visual
verification at 5 named locations, flag default-on, delete legacy
code, finalize plan + memory + ISSUES.

**Task 22 also unlocks the Adjustment 3 mitigation.** Right now
flag-on has a real FPS regression because both rendering pipelines run
in parallel (legacy renderer still does atlas-tier upload + draw,
even though WB is also building atlas state). When Task 22 lands the
dispatcher AND wires the legacy-renderer short-circuit for atlas-tier
content, that double-work disappears.

## Two unresolved decisions before Task 22 starts

These need a brainstorm checkpoint at the start of Week 4, NOT a
"just dispatch":

1. **Adjustment 4 plumbing.** `WorldEntity` doesn't carry
   `HiddenPartsMask` or `AnimPartChanges` — those live on the
   network-layer spawn record and don't make it to the render-side
   entity. Two options:
   - **A**: add `HiddenPartsMask` + `AnimPartChanges` fields to
     `WorldEntity`, populate at spawn time. Cleaner long-term; small
     network→render plumbing change.
   - **B**: thread them as separate parameters into
     `EntitySpawnAdapter.OnCreate(entity, hiddenMask, animPartChanges)`.
     Sidesteps the `WorldEntity` change but couples the spawn-handler
     to the adapter API.

   Decide before writing Task 22 because the dispatcher reads from
   `AnimatedEntityState` which currently holds defaults (empty mask +
   empty override map). Without this resolved, hidden parts won't
   actually be hidden flag-on.

2. **Surface-metadata side-table population strategy** (Task 23). The
   spec proposes: when `WbMeshAdapter.IncrementRefCount(id)` is first
   called for a GfxObj, walk its sub-meshes via `GfxObjMesh.Build`,
   write each `(gfxObjId, surfaceIdx) → AcSurfaceMetadata` entry into
   the side-table. The `_metadataPopulated: HashSet<ulong>` field
   tracks which ids have been processed.

   **But:** if the same GfxObj gets its ref count drop to zero and
   then re-incremented (LRU eviction + reload), do we re-populate?
   The metadata is invariant per-GfxObj (surface flags don't change
   with eviction), so probably no — the `HashSet` is fine. But
   verify before implementing.

## Watchouts (lessons from Weeks 1-3)

These are real, observed gotchas. Read each before going deeper.

- **The renderer is tier-blind by design (Adjustment 2).** Don't try
  to put routing decisions in `InstancedMeshRenderer` or any mesh
  uploader. Routing belongs at the **spawn-callback layer**:
  `LandblockSpawnAdapter` for atlas-tier, `EntitySpawnAdapter` for
  per-instance. Task 22's dispatcher reads from those adapters'
  per-entity state at draw time; it doesn't make tier decisions.

- **Flag-off must stay byte-identical to pre-N.4.** Every Task-22 code
  path must have a `WbFoundationFlag.IsEnabled` gate. Default-off path
  is what users see; we can't regress it.

- **WB's pipeline does work even when you're not draining its results.**
  Adjustment 3: `IncrementRefCount` triggers background mesh prep,
  texture decode, atlas allocation. `WbMeshAdapter.Tick()` already
  drains the upload queue per frame. The remaining FPS cost is
  pure dual-pipeline cost (legacy + WB doing the same upload work).
  Task 22's short-circuit fixes this.

- **`MeshRef.SurfaceOverrides`** is the per-surface texture-swap data
  carried by spawned entities. `GfxObjSubMesh.SurfaceId` is what gets
  swapped. Task 22's draw loop must consult both: the entity's
  `MeshRef.SurfaceOverrides` for explicit swaps, and otherwise the
  mesh's built-in `SurfaceId`.

- **Conformance tests catch divergences early.** Per N.1's rotation
  bug: write the conformance test BEFORE the substitution. The
  matrix-composition test (`(entityWorld) × (animation) × (restPose)`)
  is the load-bearing one for Task 22 — pin it before integrating.

- **`WbMeshAdapter.Tick()` is required.** It's already wired into
  `GameWindow.OnRender`. Task 22's dispatcher needs the upload queue
  drained BEFORE it tries to draw, so order in OnRender is:
  `_wbMeshAdapter?.Tick()` → `_wbDrawDispatcher?.Draw(...)` → other
  draw work.

- **Name retail decomp first; Phase N.4 doesn't change that rule.**
  Task 22's matrix composition uses standard graphics math — no AC-
  specific algorithms — so the "grep `named-retail/` first" workflow
  doesn't apply to the matrix code itself. But for any AC-specific
  question that surfaces during integration (e.g., "does retail
  render hidden parts as zero-alpha or skip them entirely?"), grep
  `docs/research/named-retail/acclient_2013_pseudo_c.txt` first.

## Acceptance criteria for Week 4

From the plan:

- [ ] All conformance tests pass (Tasks 3, 4, 20 — already shipped;
      verify still green after Task 22 lands).
- [ ] All component micro-tests pass (Tasks 11, 17, 18, 19, 22 —
      Task 22 adds matrix-composition tests).
- [ ] All existing tests still pass. 8 pre-existing failures don't
      count.
- [ ] Build green throughout.
- [ ] Visual verification at 5 named locations passes:
  1. Holtburg outdoor — terrain props, scenery, buildings, NPCs,
     characters all render correctly.
  2. Drudge Hideout (or comparable) — EnvCell + interior lighting +
     animated creatures.
  3. Foundry — heavy NPC traffic + customized appearances.
  4. A character with extreme palette overrides.
  5. Long roam (5+ minutes) — GPU memory stabilizes (LRU eviction
     fires).
- [ ] Memory budget enforcement actually verified (Task 13 was
      deferred to here; Task 22 makes it testable because GL resources
      finally get allocated for LRU to evict).
- [ ] Sky pass renders identically (load-bearing — sky's
      `Translucent+ClipMap` cloud sheet, raw-`Additive` fog skip,
      `Luminosity` keyframe handling all flow through the side-table
      via `AcSurfaceMetadata`).
- [ ] Flag flipped to default-on at the end (Task 26).
- [ ] Legacy code paths deleted (Task 27).
- [ ] Roadmap + memory + ISSUES updated (Task 28).

## Tasks 22-28 — quick map

Full detail is in the plan. Brief here:

- **22 — `WbDrawDispatcher` full draw loop.** ~1-2 days. Atlas-tier
  + per-instance-tier draw with matrix composition. Reads from
  `WbMeshAdapter.GetRenderData(id)` for atlas content; reads from
  `EntitySpawnAdapter.GetState(serverGuid)` for per-instance state;
  composes per-part `(entity × animation × rest-pose)` matrices;
  pushes uniforms; issues GL draws. **Also wires the legacy-
  renderer short-circuit** for atlas-tier content (the Adjustment 3
  fix).
- **23 — Surface-metadata side-table population.** ~half day. Hook
  into `WbMeshAdapter.IncrementRefCount` so that on first registration
  of a GfxObj, the side-table gets populated with one
  `AcSurfaceMetadata` per surfaceIdx (using `GfxObjMesh.Build`'s
  metadata as the source of truth).
- **24 — Sky-pass preservation check.** ~half day. Verify the sky
  pass's `NeedsUvRepeat` / `DisableFog` / `Luminosity` flow through
  the side-table to `SkyRenderer` correctly. Likely no code change;
  smoke-test sky rendering with flag on, weather/day-night cycle.
- **25 — Component micro-tests round-out.** Audit existing tests
  against the spec's Testing section. Probably nothing to add since
  Tasks 11/17/18/19/22 already cover the listed micro-tests.
- **26 — Visual verification + flag default-on.** Human-in-the-loop
  walk through the 5 named locations. If clean, flip
  `WbFoundationFlag.IsEnabled` from `== "1"` to `!= "0"` so flag-on
  becomes the default.
- **27 — Delete legacy code paths.** Remove the now-unused legacy
  upload code in `StaticMeshRenderer` + `InstancedMeshRenderer`.
  N.6 fully replaces these files anyway.
- **28 — Update roadmap + memory + ISSUES + finalize plan.** Mark
  N.4 shipped in the roadmap's Live ✓ table. File any cosmetic
  deltas as ISSUES. Add a memory note if a durable lesson emerged.
  Flip the plan's status header from "Living document — work in
  progress" to "Final state — phase shipped (merge `<sha>`)".

## Where to start

1. **Read the three "Read first" docs above end-to-end.** Especially
   the Adjustments section in the plan — those are the architectural
   constraints Task 22 must respect.
2. **Decide Adjustment 4 plumbing** (option A vs B from above). This
   is a small brainstorm checkpoint, not a multi-question
   `superpowers:brainstorming` skill invocation. Document the choice
   inline in the plan as Adjustment 6.
3. **Don't create a new worktree.** The existing branch
   `claude/quirky-jepsen-fd60f1` and worktree
   `.claude/worktrees/quirky-jepsen-fd60f1` are clean and ready.
   Submodule already initialized. Build green.
4. **Use `superpowers:subagent-driven-development`** to execute Week 4
   task-by-task. Pattern from Weeks 1-3: dispatch one subagent per
   task (or batch of related tasks), use Sonnet for implementation,
   merge to main per logical chunk, update the plan's Progress table
   as commits land.
5. **Pause for visual verification at Task 26.** This is a human-in-
   the-loop step — needs you to walk the 5 named locations.

## Open questions a fresh agent might hit

- **Q: Why did Adjustment 5 mark Task 20 (per-instance decode
  conformance) as "structural"?** Because both old and new paths call
  the same `TextureCache.GetOrUploadWithPaletteOverride` function. We
  preserved the decode logic exactly; the seam is at the call site,
  not at the algorithm. Byte-equality is automatic.

- **Q: Can I delete `InstancedMeshRenderer`?** Not in N.4. The plan
  marks it as "becomes a thin adapter in N.4, fully replaced in N.6."
  Task 27 deletes the legacy upload paths inside it but keeps the
  file as a draw-orchestration adapter until N.6.

- **Q: What's the memory budget check actually checking?** GPU memory
  stabilizes during long roam. WB's `_maxGpuMemory = 1 GB` triggers
  LRU eviction once the cache exceeds that. We verify by walking
  for 5+ minutes at radius 7 (49 landblocks visible at any time) and
  confirming GPU memory in the title bar plateaus rather than
  growing unboundedly.

- **Q: What happens if Task 22 takes longer than expected?** The
  living-document convention says document Adjustments inline. If
  Task 22 needs to split (e.g., atlas-tier draw lands first, per-
  instance tier in a follow-on commit), that's fine — just update
  the Progress table and add an Adjustment explaining the split.

## Useful greps and commands

- `dotnet build --verbosity quiet 2>&1 | tail -3` — quick build check.
- `dotnet test --verbosity quiet 2>&1 | tail -3` — full test suite.
- `git -C C:\Users\erikn\source\repos\acdream log --oneline -10` —
  recent main commits.
- `grep -rn "WbFoundationFlag.IsEnabled" src/` — every place we gate
  on the flag (audit before flipping default-on in Task 26).
- `grep -rn "_wbMeshAdapter\|_wbSpawnAdapter\|_wbEntitySpawnAdapter" src/` —
  every WB adapter wiring point.

## Smoke-test launch (PowerShell)

```powershell
# Kill any stale processes first
Get-Process -Name AcDream.App -ErrorAction SilentlyContinue | Stop-Process -Force
Start-Sleep -Seconds 4

# Flag-on at radius 7 — Week 4 dev environment
$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_USE_WB_FOUNDATION = "1"
$env:ACDREAM_STREAM_RADIUS = "7"
dotnet run --project src\AcDream.App\AcDream.App.csproj --no-build -c Debug 2>&1 |
    Tee-Object -FilePath "n4-week4-smoke.log"
```

(Drop the `ACDREAM_USE_WB_FOUNDATION` line for flag-off comparison.)

## Adjustments index — quick reference

For full text, see the plan document (each is a `### Adjustment N`
subsection under Task 6's old position, in chronological order):

1. **`DefaultDatReaderWriter` discovery** (2026-05-08) — no
   dat-reader bridge needed; WB ships a usable concrete
   implementation.
2. **Renderer is tier-blind** (2026-05-08) — routing belongs at
   spawn callbacks, not in the renderer.
3. **FPS regression = dual-pipeline cost** (2026-05-08) — both
   pipelines run in parallel until Task 22's short-circuit lands.
4. **`WorldEntity` lacks HiddenParts/AnimPartChange fields**
   (2026-05-08) — plumbing deferred; Task 22 needs to resolve
   (option A: add fields; option B: thread as separate args).
5. **Task 20 is structural** (2026-05-08) — same function called
   both paths, byte-equality automatic, no test file needed.