From ac2af96b15d6f60a7512c100e21ab207f4c69264 Mon Sep 17 00:00:00 2001 From: Erik Date: Sat, 11 Apr 2026 18:30:55 +0200 Subject: [PATCH] docs(plan): roadmap with every observed defect mapped to a phase MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) --- docs/plans/2026-04-11-roadmap.md | 197 +++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/plans/2026-04-11-roadmap.md diff --git a/docs/plans/2026-04-11-roadmap.md b/docs/plans/2026-04-11-roadmap.md new file mode 100644 index 0000000..a8354e8 --- /dev/null +++ b/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.