docs: movement deep dive — AC2D + holtburger cross-reference

Exhaustive analysis of two working AC clients revealing three critical
findings that reshape acdream's movement system:

1. Server-authoritative Z: neither AC2D nor holtburger computes local
   terrain Z for the player. AC2D sends keys, receives position. Holtburger
   dead-reckons for smoothing but the server overrides.

2. Terrain split formula mismatch: AC2D and ACViewer's render path use
   0x0CCAC033-based FSplitNESW; WorldBuilder (our source) uses a different
   214614067-based physics formula. Our terrain mesh triangulation doesn't
   match the real AC client's, causing Z mismatches on slopes.

3. Movement deduplication: MoveToState sent once per state change, not per
   frame. AutonomousPosition heartbeat every 1 second.

Also adds AC2D to CLAUDE.md reference repos section.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Erik 2026-04-12 21:52:12 +02:00
parent 29fe0c0714
commit 5cd776914a
2 changed files with 343 additions and 0 deletions

View file

@ -182,6 +182,16 @@ these, ideally all four:
the message-builder layer. ACE shows what the server expects;
holtburger shows what a real client actually sends.
- **`references/AC2D/`** — **C++ AC client emulator.** Oldest reference,
fixed-function OpenGL, but has the **real AC terrain split formula**
(`FSplitNESW` with constants `0x0CCAC033`, `0x421BE3BD`, `0x6C1AC587`,
`0x519B8F25`) which differs from WorldBuilder's physics-path formula.
Also has the complete `0xF61C` movement packet format with flag bits
and the `stMoveInfo` sequence counters. Key lesson from AC2D: it does
NOT do client-side terrain Z — it sends movement keys to the server
and uses the server's authoritative Z. See
`docs/research/2026-04-12-movement-deep-dive.md` for the full analysis.
Pattern: when you encounter an unknown behavior, grep all four for the
relevant term, read each hit, and compose a multi-source understanding
BEFORE writing acdream code. A single reference can be misleading; the