Files

T

sindoring c2be8ae95e docs(M01): claim canonical coordinate contract

Work-Package: M01-FND-COORDS-001
Agent: sindo-main-codex
Tests: not applicable (claim only)
Fidelity: scope references merged M00 build 12340 coordinate evidence

2026-07-13 13:22:02 +04:00

3.5 KiB

Raw Blame History

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: active
Done: repository/reference audit and contract scope
Next: ADR, fixtures, value objects and mapper implementation
Blocked by:

3.5 KiB Raw Blame History