sindoring
dd412e6d0d
Work-Package: M01-QAR-INTEGRATOR-CLOSEOUT-001 Agent: sindo-main-codex Tests: all M01 domain gates, unified renderer dry-run, coordination and documentation gates Fidelity: five build-12340 points, raw ADT and mapped AzerothCore spawn evidence; no 1:1 claim
5.3 KiB
5.3 KiB
M01-FND-COORDS-001 — Canonical coordinate contracts
Ownership
- Target: M01
- Program: FND
- Owner/Agent ID: sindo-main-codex
- Branch:
work/sindo-main-codex/m01-coordinate-mapper - Lease expires UTC: 2026-07-15
- Integrator: M01 milestone integrator
Outcome
Introduce scene-free value objects for canonical WoW, server, ADT placement,
ADT tile/chunk/local and Godot world coordinate spaces, plus the single pure
CoordinateMapper contract for position and world-yaw conversions.
Non-goals
- Migrating
StreamingWorldLoader, native parsers, sky, player or renderer code. - Defining model-specific MDDF/MODF Euler rotation corrections.
- Introducing
StreamingFocus, typed IDs or a test framework dependency. - Claiming visual parity from arithmetic round trips.
Paths
- Exclusive:
src/domain/coordinates/**,src/tools/verify_coordinate_mapper.gd,docs/modules/coordinate-mapping.md,docs/adr/0001-canonical-world-coordinates.md - Shared/hotspots:
docs/modules/README.md, this claim - Generated/ignored: Godot import metadata and local test output
Contracts and data
- Public API/events: immutable coordinate value objects and pure mapper methods
- Schema/format version: no persisted format; contract version 1 in module docs
- Migration/compatibility: additive contract; existing renderer conversions remain unchanged until a later consumer migration package
- Consumers: future renderer, network, gameplay and server-data adapters
- Rollout order: contract and fixtures first, then native/parser and renderer consumers
Dependencies
- Requires: merged M00 build 12340 coordinate calibration evidence
- Blocks: M01 renderer coordinate migration and
StreamingFocus - External state: no proprietary inputs; reference formulas are source-only evidence
Verification
- Commands: headless coordinate contract probe, headless project load, coordination and documentation gates
- Fixtures: five build 12340 camera points, ADT map center/edge/boundary points, server/ADT/Godot round trips and yaw normalization cases
- Fidelity evidence: M00 observed build 12340 positions plus independent OpenRealm/WoWee and TrinityCore grid formulas
- Performance budget: constant-time scalar arithmetic with no allocation beyond result values
Documentation deliverables
- Inline public API docs: every public value object and mapper method
- Module specification: purpose, public API, inputs/outputs, ownership, errors and source map
- Data-flow diagram: server/ADT/canonical/Godot mappings
- Dependency diagram: canonical contract consumers and forbidden scene dependency
- Sequence/state diagrams: not applicable; mapper is synchronous and stateless
- ADR: coordinate axes, units, tile indexing and compatibility rollout
Simplicity and naming
- Important names introduced:
CanonicalWowWorldPosition,ServerWorldPosition,AdtPlacementPosition,AdtTileCoordinate,AdtChunkCoordinate,AdtTileLocalPosition,GodotWorldPosition,WorldYaw,CoordinateMapper - Simplest considered solution: scalar immutable value objects and one pure mapper
- Rejected complexity/abstractions: generic vector-space framework, matrices, dependency injection and a third-party test framework
- Unavoidable complexity and justification: distinct source spaces prevent silent axis swaps
- Measured optimization evidence: not applicable
Status
- State: ready-for-review
- Done: repository/reference audit, ADR, immutable value objects, pure mapper, build 12340/boundary/yaw fixtures, module specification and repository gates
- Next: integrator review and merge before renderer/native consumer migration
- Blocked by:
Handoff
- Commit:
f45695c - Branch:
work/sindo-main-codex/m01-coordinate-mapper - Outcome: additive contract for canonical/server/ADT/Godot positions, ADT tile/chunk/local ownership and world-facing yaw; no existing consumer changed
- Public contracts: contract version 1 documented in
docs/modules/coordinate-mapping.md; no persisted schema or cache change - Verification: coordinate mapper PASS (5 golden points, 8 tile boundaries,
5 yaw cases); M00 coordinate calibration PASS (5 points, maximum error
0.000015); renderer manifest, coordination, documentation, dependency and whitespace checks passed; headless project load completed with expected missing proprietary-data diagnostics in the isolated worktree - Fidelity: observed build 12340 positions match within
0.002yard; formulas cross-checked against TrinityCore, OpenRealm and WoWee; visual parity is not claimed - Migration/rebuild: none for this additive package; consumers migrate only after merge and must preserve renderer checkpoints
- Remaining risks: native loaders and renderer still use manual conversions; MDDF/MODF Euler mapping is intentionally unresolved; server-spawn integration and finite-value adapter validation remain later M01 packages
- Recommended merge order: this contract first, coordinate fixtures/server-spawn audit second, renderer/native consumers third, manual-conversion search gate last
- Documentation: ADR 0001; coordinate-mapping module spec with data-flow and dependency diagrams; inline API documentation on all public symbols