sindoring
c2be8ae95e
Work-Package: M01-FND-COORDS-001 Agent: sindo-main-codex Tests: not applicable (claim only) Fidelity: scope references merged M00 build 12340 coordinate evidence
86 lines
3.5 KiB
Markdown
86 lines
3.5 KiB
Markdown
# M01-FND-COORDS-001 — Canonical coordinate contracts
|
|
|
|
<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-15 -->
|
|
|
|
## 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:
|
|
|