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

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.