sindoring
1c0dfc761d
Work-Package: M01-FND-COORDS-001 Agent: sindo-main-codex Tests: coordination and documentation gates passed Fidelity: handoff records five build 12340 golden coordinate points
112 lines
5.2 KiB
Markdown
112 lines
5.2 KiB
Markdown
# M01-FND-COORDS-001 — Canonical coordinate contracts
|
|
|
|
<!-- OPENWC_CLAIM:M01-FND-COORDS-001:sindo-main-codex:2026-07-15 -->
|
|
<!-- OPENWC_HANDOFF:READY:M01-FND-COORDS-001:f45695c -->
|
|
|
|
## 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.002` yard; 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
|