docs(plan): roadmap with every observed defect mapped to a phase

Captures all the "this looks wrong" findings from the Phase 5 visual
verification and assigns each to a future phase. Top-of-document is
phases done, then phases ahead in suggested order, then a quick
lookup table that maps user complaints to their owning phase.

Phases ahead:
  6  Animation system (creature poses, walk/attack motions, breathe-idle)
  7  Multi-floor interiors + dungeons (second floors, foundry interior,
     subterranean rooms)
  8  Player input → server (movement, interact, ack pump, combat)
  9  Visual polish (portals, mesh-origin offsets, exact palette ranges,
     lighting/shadows)
 10  UI / HUD (chat, inventory, character panel, spellbook, minimap)
 11  Sound (SoundTable, audio engine, 3D positional audio)
 12  Streaming + perf (chunked landblock loading, frustum culling, LOD,
     background net thread)

Each phase entry has: what it owns, what it requires, references in the
existing references/ tree, and rough effort estimate.

Document is intentionally a living roadmap — updated whenever a phase
lands or when a new defect is observed that doesn't fit the existing
buckets.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/plans/2026-04-11-roadmap.md

@@ -0,0 +1,197 @@
+# acdream — phase roadmap
+
+**Status:** Living document. Updated 2026-04-11 after Phase 5 visual verification.
+**Purpose:** Every observed defect and missing feature has a named phase that owns it. When something looks wrong, look here first to find which phase will fix it.
+
+---
+
+## Phases done
+
+| Phase | What landed | Verification |
+|---|---|---|
+| **1** | Terrain rendering, plugin host scaffold | Visual ✓ |
+| **2a** | Static stabs/buildings (126 entities) | Visual ✓ |
+| **2b** | Textured 3×3 landblock grid + FlyCamera + IGameState | Visual ✓ |
+| **2c** | Procedural scenery (419 trees/rocks/bushes) | Visual ✓ |
+| **2d** | Interior EnvCell walker (475 static interior objects) | Visual ✓ |
+| **3a/3b** | Directional sun lighting + per-vertex terrain normals | Visual ✓ |
+| **3c** | Per-cell terrain texture blending (alpha atlas) | Visual ✓ |
+| **4** | Full UDP codec + handshake + character login + WorldSession | Live ✓ |
+| **5** | ObjDesc: AnimPart + TextureChanges + SubPalettes + ObjScale + Placement.Resting | Live ✓ partial |
+
+**Phase 5 status:** characters, doors, signs, NPCs, statues all spawn and render with correct positions, scales, and per-entity textures + palettes. The Holtburg sign now stands upright thanks to Resting placement. The Nullified Statue of a Drudge renders at correct scale and color but in the wrong pose (deferred — see Phase 6).
+
+---
+
+## Phases ahead, in suggested order
+
+### Phase 6 — Animation system
+**Owns:**
+- Drudge statue rendering in aggressive crouch instead of upright "Resting" stance (creatures don't have a Resting placement frame; their idle pose comes from animations, not Setup placements)
+- All characters and NPCs rendering in Setup-default pose (T-pose-ish or default crouch) instead of breathing/idling
+- No walk/attack/gesture animations for any entity
+- Player character has no movement animation when WASD-flying
+
+**What it requires:**
+- `MotionTable` dat parser (animation frame keyframes per motion id)
+- `Animation` dat parser (the actual frame data)
+- Per-entity animation state: current motion id, current frame, time-since-frame-start
+- Per-frame interpolation between keyframes
+- Apply interpolated frame to PartArray.Frames per part (replaces our static `Setup.PlacementFrames[Default]` lookup)
+- Default-on-spawn motion: `Motion_Ready` or similar idle motion for every alive creature
+
+**Reference:**
+- `references/ACViewer/ACViewer/Physics/PartArray.cs::UpdateParts` — the per-frame motion application loop
+- `references/ACViewer/ACViewer/Physics/Animation/AnimSequence.cs` — sequence interpolation
+- `references/ACE/Source/ACE.DatLoader/FileTypes/MotionTable.cs` — motion table layout
+
+**Estimated effort:** 1-2 sessions. The motion system is the single biggest visual quality lever left.
+
+---
+
+### Phase 7 — Multi-floor interiors + dungeons
+**Owns:**
+- "Interior houses missing second floors" — our Phase 2d EnvCell walker only walks the ground-floor cells of a landblock and stops
+- "Doors that lead under something" — opening a door reveals subterranean cells we don't load
+- Dungeons (the Holtburg foundry interior, mines, etc.) — entirely missing
+- Building roofs and upper-story walls
+
+**What it requires:**
+- Walk EnvCell `0xAAAA0100+N` for the FULL range, not just N=0 (currently we stop early for some setups)
+- Recognize "stairs" / "floor transitions" in the cell graph and walk them
+- Handle dungeon landblock format: `0xAAAA0000` family with interior-only cell hierarchies
+- Possibly: load the dungeon when the player approaches a door that leads to it (streaming)
+
+**Reference:**
+- ACViewer's level loader and ACE's `EnvCell` parsing
+- WorldBuilder's dat browser for inspecting EnvCell structures of multi-floor buildings
+
+**Estimated effort:** 1 session, mostly debugging the cell-walk graph.
+
+---
+
+### Phase 8 — Player input → server
+**Owns:**
+- "I can fly around in acdream but I'm not actually MOVING in the game world from the server's perspective"
+- Standing still while live → server eventually drops us (no ack pump → no heartbeat)
+- Can't pick up items, click NPCs, talk to vendors, cast spells
+- No combat
+
+**What it requires:**
+- Outbound `PlayerAutonomousMove` GameMessage from acdream → server
+- Outbound `Ack` pump (background timer that sends `AckSequence` packets every ~250ms)
+- Outbound interact: `Use`, `UseWithTarget`, `PickUp`
+- Outbound chat: `SendTell`, `SendChat`
+- Map acdream's WASD camera position to server-space player position
+- Resolve character collision against terrain (so the server accepts the move)
+
+**Reference:**
+- ACE.Server `Network/Handlers/MovementHandler.cs`, `UseObjectHandler.cs`
+- holtburger session/send.rs for the outbound side patterns
+
+**Estimated effort:** 1-2 sessions. The ack pump is small; the move-and-interact protocol surface is large.
+
+---
+
+### Phase 9 — Visual polish
+**Owns:**
+- Portals rendering as black squares (probably needs special material handling — clipmap + animated UV)
+- Some entities with mesh-origin offsets that look wrong (non-Resting setups still float or sink)
+- Skin/hair/eye palette ranges on characters that aren't quite right
+- Lighting shadows and reflections
+- Better color tone overall
+
+**What it requires:**
+- Portal-specific shader path or texture animation system
+- Per-Setup mesh-origin diagnostic and fixup (or accept and document)
+- Verify palette range offsets/lengths against retail screenshots
+- Optionally: shadow maps, dynamic lighting
+
+**Estimated effort:** 1 session. Mostly tuning and edge cases.
+
+---
+
+### Phase 10 — UI / HUD
+**Owns:**
+- No chat window
+- No inventory display
+- No character info panel
+- No spell book
+- No minimap
+- No nameplates above characters/NPCs
+
+**What it requires:**
+- 2D rendering layer (Silk.NET supports this via ortho projection + a separate shader)
+- Font rendering (port a TTF rasterizer, e.g. FreeType bindings via Silk.NET, or use bitmap fonts)
+- Layout system or fixed-position widgets
+- Bind to GameState events for inventory updates, chat messages, etc.
+
+**Estimated effort:** 2-3 sessions. UI is unbounded.
+
+---
+
+### Phase 11 — Sound
+**Owns:**
+- No audio at all
+
+**What it requires:**
+- `SoundTable` parser (each weenie has a SoundTable for footsteps, hits, voice)
+- Sound dat decode (probably WAV-like format)
+- Audio engine (NAudio or OpenAL via Silk.NET.OpenAL)
+- Per-entity 3D positional audio
+- Music
+
+**Estimated effort:** 1-2 sessions.
+
+---
+
+### Phase 12 — Streaming + perf
+**Owns:**
+- Currently we render a fixed 3×3 landblock window. Walking out of it would crash or show emptiness.
+- No frustum culling. Some parts of the world are always submitted.
+- No LOD. Distant trees use the same vertex count as near ones.
+- Single-threaded packet pump. Could miss packets under load.
+
+**What it requires:**
+- Chunk-based terrain loading (deferred Phase 3d work — port WorldBuilder's `TerrainRenderManager`)
+- Visibility scan as the player moves; load nearby chunks, unload far ones
+- Frustum cull chunks before submitting draw calls
+- Background thread for net I/O so render thread is never blocked
+- Async dat decoding to avoid hitches when new entities arrive
+
+**Estimated effort:** 1-2 sessions for streaming, additional polish ongoing.
+
+---
+
+## Things explicitly out of scope
+
+- **Server emulation** — we use ACE for server, never reimplement
+- **Account creation** — direct user to ACE's auto-create or manual DB
+- **Anti-cheat / GMS / live-ops** — irrelevant for personal use
+- **Cross-platform** — Windows-only is fine; Silk.NET is cross-platform but the dat assumptions assume retail Windows install paths
+
+---
+
+## "When will my specific complaint be fixed?" — quick lookup
+
+| Observation | Phase |
+|---|---|
+| Drudge statue in wrong pose (crouch) | **Phase 6 (Animation)** |
+| Characters in T-pose / wrong idle | **Phase 6** |
+| Houses missing second floors | **Phase 7 (Interiors)** |
+| Doors leading underground / nowhere | **Phase 7** |
+| Foundry interior missing | **Phase 7** |
+| Portals are black squares | **Phase 9 (Polish)** |
+| Holtburg sign half-buried | **Phase 5d FIXED** ✓ |
+| Statue too small / wrong size | **Phase 5c FIXED** ✓ |
+| Characters naked | **Phase 5a FIXED** ✓ |
+| Wrong colors on characters / statue | **Phase 5b FIXED** ✓ |
+| Foundry statue not appearing at all | **Phase 4.7 FIXED** ✓ |
+| Skin/hair color slightly off | **Phase 9** (likely a palette range tweak) |
+| Walking around doesn't move me on the server | **Phase 8 (Player input)** |
+| Can't talk to NPCs | **Phase 8** |
+| No chat window | **Phase 10 (UI)** |
+| No sound | **Phase 11** |
+| Can't walk to the next landblock | **Phase 12 (Streaming)** |
+
+If you see something not on this list, tell me and I'll add it.