28-task plan covering 4 weeks of work organized as:
- Week 1 (Tasks 1-10): WB plumbing + atlas for static scenery + conformance
- Week 2 (Tasks 11-15): streaming integration + memory budget verification
- Week 3 (Tasks 16-21): per-instance customization + animation
- Week 4 (Tasks 22-28): full draw dispatcher + visual verification + ship
Living document — task checkboxes marked as commits land; adjustments
appended in-place rather than rewriting earlier tasks. Conformance
tests run before substitution per N.1/N.3 pattern. Behind
ACDREAM_USE_WB_FOUNDATION=1 feature flag during weeks 1-3.
CLAUDE.md updated with a "Currently in flight" pointer in the Roadmap
discipline section so future agents pick up the plan as authoritative
for rendering work.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adopting WB's ObjectMeshManager + TextureAtlasManager as acdream's
shared rendering infrastructure. Two-tier split: atlas for shared
procedural content (terrain props, scenery, buildings), per-instance
path for server-spawned customized entities (characters, creatures,
equipped items).
Animation handled by composing per-frame override matrices from our
existing AnimationSequencer with cached rest poses at draw time.
Cache stays valid; AnimationSequencer untouched.
Streaming-loader integration: ~200 LOC adapter shim wires landblock
load/unload to IncrementRefCount/DecrementRefCount; pending-spawn
list mechanism preserved.
Surface metadata (Translucency/Luminosity/Diffuse/SurfOpacity/
NeedsUvRepeat/DisableFog) preserved via side-table keyed by
(GfxObjId, surfaceIdx) — no fork patches required.
Three algorithmic conformance tests run before substitution per the
N.1/N.3 pattern. Visual verification at 5 named locations.
3-4 weeks, single shippable phase. Foundation enables N.5-N.9.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Roadmap: N.3 row added to shipped table; sub-phase block updated from
ahead-estimate to shipped summary. Document header date bumped.
Plan: docs/superpowers/plans/2026-05-08-phase-n3-texture-decode-via-wb.md
captures the audit + per-format substitution strategy + A8 isAdditive
divergence resolution that drove this phase.
No ISSUES.md update — visual verification at Holtburg is the remaining
gate; if the A8 non-additive change produces a visible delta on entity
textures, an issue gets filed there.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Adds two design docs and a roadmap entry for the strategic shift
from "port retail rendering algorithms ourselves" to "depend on a
fork of Chorizite/WorldBuilder for rendering + dat-handling."
- docs/superpowers/specs/2026-05-08-phase-n-worldbuilder-migration-design.md
— parent design: integration model (fork + submodule), 10 sub-phases
(N.0 setup through N.10 GL consolidation), strangler-fig phasing
with per-phase feature flags, retail-decomp boundary clarified for
what WB does NOT cover (network, physics, animation, motion, UI,
plugin, audio, chat).
- docs/superpowers/specs/2026-05-08-phase-n1-scenery-via-wb-helpers-design.md
— N.1 detailed design: replace IsOnRoad / DisplaceObject /
slope-normal calc / rotation / scale inside SceneryGenerator.Generate()
with calls to WB's SceneryHelpers + TerrainUtils. Keep data flow,
ScenerySpawn shape, and renderer integration. Add small LandBlock →
TerrainEntry[] adapter. Feature flag ACDREAM_USE_WB_SCENERY=1.
- docs/plans/2026-04-11-roadmap.md — Phase N entry added between
Phase M and Phase J. Lists all 10 sub-phases with effort estimates.
Fork already created at https://github.com/eriknihlen/WorldBuilder.
N.0 setup (replace references/WorldBuilder/ snapshot with submodule,
add project references, build green) is the next implementation step.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Visual verification of L.3.1-as-originally-scoped (commit ae79e34
through e08accf) revealed that InterpolationManager corrections alone
cannot produce smooth motion — retail also relies on animation root
motion (the L.3.2 PositionManager work, originally deferred). The two
halves are functionally inseparable.
Spec changes:
- L.3.1 sub-lane absorbs L.3.2's PositionManager
- New section: PositionManager architecture (pure-function ComputeOffset
returning Vector3 delta; combines body-local seqVel * dt rotated to
world + InterpolationManager.AdjustOffset correction)
- New section: IsGrounded plumbing through EntityPositionUpdate (the
PositionFlags.IsGrounded=0x04 is already parsed; just expose it)
- New section: retail-faithful jump pipeline (airborne → no-op per
MoveOrTeleport's has_contact=0 semantics; landing detected via first
IsGrounded=true UP after airborne)
- Acceptance criteria updated for combined scope
- Implementation order: 6 commits remaining (after the revert at 1641d6e)
- Stall-blip TAIL annotation (Task 0 resolution) folded in
L.3.3 (MoveToManager) stays a separate sub-lane.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Port retail's InterpolationManager + MoveOrTeleport routing into
acdream so remote players, creatures, and NPCs stop popping at every
server position update and instead glide smoothly between sparse
authoritative updates the way retail does.
Three sub-lanes (incremental, each visually verifiable):
- L.3.1 — InterpolationManager core + routing + Omega + soft-snap teardown
- L.3.2 — PositionManager (root-motion + interp-offset combiner)
- L.3.3 — MoveToManager (server-controlled creature MoveTo)
This commit specs L.3.1 in detail and sketches L.3.2/L.3.3.
Research baseline (cdb live-trace + named-decomp dive 2026-05-02)
captured in docs/research/2026-05-02-remote-entity-motion/
resolved-via-cdb.md. All key constants confirmed from binary, not
guessed: MAX_PHYSICS_DISTANCE=96, MAX_INTERPOLATED_VELOCITY_MOD=2.0,
MAX_INTERPOLATED_VELOCITY=7.5, MIN_DISTANCE_TO_REACH_POSITION=0.20,
DESIRED_DISTANCE=0.05, queue cap 20, stall window 5/30%/3.
Rollout: ACDREAM_INTERP_MANAGER=1 env-var gate during development
(dual-path), single cleanup commit after visual verification removes
the flag + old hard-snap path + dead RemoteMotion soft-snap fields.
Test plan: ~15 unit tests against the InterpolationManager class
(pure-data, no game/window deps). Visual verification primary —
parallel retail observer of +Acdream walking/running/strafing/
jumping/turning, all should glide.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Four-layer design for retail-faithful movement: speed from RunRate,
charged jump, BSP collision from decompiled CTransition, cell-based
object collision. Decompile-first methodology per CLAUDE.md.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Comprehensive spec for completing the physics/movement system:
CellPortal-based indoor/outdoor/room-to-room transitions via
sphere-plane intersection, multi-landblock boundary crossing,
momentum-preserving jump with gravity arc, portal-space state
machine for teleports, Setup.StepUpHeight hookup, and
scenery-on-road exclusion fix.
Replaces the current "outdoor heightmap sampler with disabled
indoor transitions" with the full world-navigation system AC's
client uses. 12 acceptance criteria, ~20 new unit tests planned.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Tab-toggled player mode with WASD ground walking, A/D + mouse
turning, Z/X strafing, Shift for run, third-person chase camera,
local walk/run/turn/idle animations, and outbound MoveToState +
AutonomousPosition server messages. Uses PhysicsEngine from B.3
for collision-resolved positions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
5-task TDD plan: TerrainSurface (outdoor heightmap Z + cell ID),
CellSurface (indoor floor polygon projection via barycentric interp),
PhysicsEngine (top-level resolver with step-height + cell transitions),
GameWindow integration (populate from streaming), and roadmap update.
~16 new unit tests with fake data. No dat files or rendering needed.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pure-computation collision engine for ground-based entity movement.
Three components: TerrainSurface (outdoor heightmap Z interpolation),
CellSurface (indoor EnvCell floor polygon projection), PhysicsEngine
(top-level resolver with step-height enforcement, outdoor/indoor
cell transitions via CellPortals, and gravity reporting).
Uses PhysicsPolygons from CellStruct for walkable surfaces with
brute-force polygon iteration (< 20 polys per cell). BSP tree
acceleration deferred — same collision fidelity, simpler code.
Standalone module with no rendering or networking dependencies.
~15-20 unit tests with fake data covering flat terrain, slopes,
stairs, wall rejection, and cell transitions. Integration with
the streaming system via ApplyLoadedTerrainLocked. Consumed by
Phase B.2 (player movement mode, separate spec).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Review follow-up from commit 11df793. Three fixes:
1. Visible semantics: StreamingRegion.Visible now strictly describes the
current (2r+1)×(2r+1) window, not window + hysteresis retainees.
Added a parallel Resident property exposing the actual loaded set
(window + hysteresis buffer). This matters because StreamingController
(next task) reads these to decide what to render vs what to unload;
conflating them in one set would have forced awkward post-processing
downstream.
2. Doc/code disagreement: updated the RecenterTo and RegionDiff doc
comments from "radius + 1" to "radius + 2" to match the actual
implementation (which is what the tests require). Also updated the
plan doc so future readers don't hit the same contradiction.
3. Edge-clamping test coverage: added a single-axis edge test
(cx=0, cy=50 → 15 entries) and an ID-encoding test (radius=0 at
0x12,0x34 → 0x1234FFFE) so a swapped-shift bug in EncodeLandblockId
or an asymmetric off-by-one would fail a test instead of passing
silently.
9 tests green, full suite regressions-free.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
9-task TDD plan for the first chunk of Phase A (Foundation): the
streaming landblock loader. Covers StreamingRegion (pure data +
hysteresis diff), LandblockStreamer (background worker + channels),
GpuWorldState (render-thread entity registry), StreamingController
(glue), TerrainRenderer.RemoveLandblock, GameWindow wiring (env var,
camera/player center switch, Dispose), scenery + interior integration,
and the roadmap-shipped-table update.
Each task is a full TDD cycle: failing test, run, minimal impl, run,
commit. ~16 new unit tests land alongside the implementation.
Phase A.2 (frustum culling) and A.3 (net I/O thread) get their own
plans once A.1 ships — they're independent subsystems per the
brainstorming skill's decomposition guidance.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Output of a brainstorming session after Phase 6/7.1/9.1/9.2 shipped
and the lifestone crystal bug was isolated. Two documents:
1. docs/plans/2026-04-11-roadmap.md — strategic roadmap replacing
the stale post-Phase-5 version. Reflects what's actually shipped,
reorganizes upcoming work into Phases A (Foundation), B (Gameplay),
C (Polish — includes VFX/particles, dynamic lights, palette tuning,
double-sided translucents), D (UI + Sound), and E (long-tail).
Updates the "when will my complaint be fixed" quick-lookup with
the correct phase for portals (VFX, not shader tricks as previously
claimed), smoke, fireplace fire, and everything we fixed this
session. Phase ordering: A → B → (C/D in parallel) → E.
2. docs/superpowers/specs/2026-04-11-foundation-phase-design.md —
detailed implementation spec for Phase A only. Covers the four
sub-pieces (streaming landblock loader, frustum culling, net I/O
thread, async dat decoding folded into the streaming worker),
their components, data flow, error handling, testing strategy,
and commit-point ordering. Includes non-goals to prevent scope
creep.
No code changes yet. The spec goes to user review next, then into
the writing-plans skill for a detailed implementation plan.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
