236 lines
14 KiB
Markdown
236 lines
14 KiB
Markdown
# Coordinate Mapping
|
|
|
|
## Metadata
|
|
|
|
| Field | Value |
|
|
|---|---|
|
|
| Status | Implemented |
|
|
| Target/work package | `M01-FND-COORDS-001`, `M01-FND-COORD-TILE-AXIS-002`, `M01-QAR-COORD-FIXTURES-001` |
|
|
| Owners | Foundation/domain |
|
|
| Last verified | Worktree `work/sindo-main-codex/m01-coordinate-fixtures`, 2026-07-13 |
|
|
| Profiles/capabilities | All profiles; contract version 2 |
|
|
|
|
## Purpose
|
|
|
|
Provide scene-free value objects and one pure `CoordinateMapper` for positions,
|
|
ADT grid ownership and world-facing yaw. The module makes every source space
|
|
explicit before renderer, network, gameplay and authoring consumers migrate.
|
|
|
|
## Non-goals
|
|
|
|
- Reading ADT, packet, SQL or scene data.
|
|
- Constructing `Vector3`, `Transform3D`, Node or Resource values.
|
|
- Correcting M2/WMO local axes or MDDF/MODF Euler rotations.
|
|
- Selecting maps, validating terrain height or owning streaming focus.
|
|
- Persisting coordinate values in this work package.
|
|
|
|
## Context and boundaries
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Server[Server / movement X,Y,Z] --> ServerPosition[ServerWorldPosition]
|
|
ADT[MDDF/MODF X,height,Z] --> AdtPosition[AdtPlacementPosition]
|
|
ServerPosition --> Mapper[CoordinateMapper]
|
|
AdtPosition --> Mapper
|
|
Mapper --> Canonical[CanonicalWowWorldPosition]
|
|
Canonical --> Tile[AdtTileCoordinate + AdtTileLocalPosition]
|
|
Canonical --> GodotPosition[GodotWorldPosition]
|
|
GodotPosition --> Adapter[Future scene/render adapter]
|
|
Adapter --> Vector[Vector3 at boundary]
|
|
Scene[Node / Camera3D / scene lookup] -. forbidden .-> Mapper
|
|
```
|
|
|
|
Allowed dependencies:
|
|
|
|
- GDScript scalar math and `RefCounted` lifetime;
|
|
- other value objects in `src/domain/coordinates`;
|
|
- callers in network, gameplay, render and server-data adapters.
|
|
|
|
Forbidden dependencies:
|
|
|
|
- `Node`, `Resource`, SceneTree, Camera3D and global scene lookup;
|
|
- packet buffers, SQL rows, asset parsers and renderer state;
|
|
- `Vector3` as a public mapper input or output;
|
|
- model-specific placement corrections.
|
|
|
|
## Public API
|
|
|
|
| Symbol | Kind | Purpose | Thread/lifetime | Errors |
|
|
|---|---|---|---|---|
|
|
| `CanonicalWowWorldPosition` | Immutable value | Client/server X/Y/Z in yards | Any thread; caller-owned reference | No bounds validation |
|
|
| `ServerWorldPosition` | Immutable value | Server/wire X/Y/Z in yards | Any thread; caller-owned reference | No adapter validation |
|
|
| `AdtPlacementPosition` | Immutable value | MDDF/MODF X/height/Z fields | Any thread; caller-owned reference | No file validation |
|
|
| `GodotWorldPosition` | Immutable value | Godot east/up/south scalars | Any thread; caller-owned reference | Does not create `Vector3` |
|
|
| `AdtTileCoordinate` | Immutable value | `Map_tileX_tileY.adt` indices | Any thread; caller-owned reference | `is_within_map_grid()` reports invalid indices |
|
|
| `AdtTileLocalPosition` | Immutable value | East/height/south offsets from tile north-west corner | Any thread; caller-owned reference | Values are intentionally unclamped |
|
|
| `AdtChunkCoordinate` | Immutable value | MCNK X-east/Y-south indices inside one tile | Any thread; caller-owned reference | `is_within_map_grid()` reports invalid indices |
|
|
| `CanonicalWowWorldYaw` | Immutable value | Canonical world yaw in radians | Any thread; caller-owned reference | Constructor does not normalize |
|
|
| `ServerWorldYaw` | Immutable value | Movement orientation in radians | Any thread; caller-owned reference | Constructor does not normalize |
|
|
| `GodotWorldYaw` | Immutable value | Godot Y-axis world yaw in radians | Any thread; caller-owned reference | Constructor does not normalize |
|
|
| `CoordinateMapper.server_to_canonical` / inverse | Pure static methods | Preserve server X/Y/Z as canonical | Synchronous; new result value | Null input is a caller contract violation |
|
|
| `CoordinateMapper.canonical_to_godot` / inverse | Pure static methods | Apply Y-up renderer basis and map offset | Synchronous; new result value | Non-finite scalars propagate |
|
|
| `CoordinateMapper.canonical_to_adt_placement` / inverse | Pure static methods | Convert ADT placement field basis | Synchronous; new result value | Non-finite scalars propagate |
|
|
| `CoordinateMapper.canonical_to_adt_tile` | Pure static method | Compute unclamped filename indices | Synchronous; new result value | Out-of-map result remains invalid |
|
|
| `CoordinateMapper.canonical_to_adt_tile_local` / inverse | Pure static methods | Split/reconstruct tile-local position | Synchronous; new result value | Caller validates tile ownership |
|
|
| `CoordinateMapper.adt_tile_local_to_chunk` | Pure static method | Compute unclamped MCNK indices | Synchronous; new result value | Boundary/out-of-range remains diagnosable |
|
|
| World-yaw mapper methods | Pure static methods | Normalize and cross the world-basis boundary | Synchronous; new result value | Non-finite input is unsupported |
|
|
|
|
## Inputs and outputs
|
|
|
|
| Direction | Contract/data | Producer | Consumer | Ownership | Thread/lifetime |
|
|
|---|---|---|---|---|---|
|
|
| Input | `ServerWorldPosition`, `ServerWorldYaw` | Future protocol/server adapter | `CoordinateMapper` | Immutable caller value | Any thread, call duration |
|
|
| Input | `AdtPlacementPosition` | Future ADT adapter | `CoordinateMapper` | Immutable caller value | Any thread, call duration |
|
|
| Input | `CanonicalWowWorldPosition`, `CanonicalWowWorldYaw` | Gameplay/content/domain | `CoordinateMapper` | Immutable caller value | Any thread, call duration |
|
|
| Output | `CanonicalWowWorldPosition` | `CoordinateMapper` | Gameplay/content/adapters | New immutable value | Caller-owned reference |
|
|
| Output | `AdtTileCoordinate`, `AdtTileLocalPosition`, `AdtChunkCoordinate` | `CoordinateMapper` | Streaming/content adapters | New immutable values | Caller-owned references |
|
|
| Output | `GodotWorldPosition`, `GodotWorldYaw` | `CoordinateMapper` | Future render/scene adapter | New immutable values | Caller-owned references |
|
|
| Test input | `coordinate_golden_points.json` schema 1 | Pinned public server row plus private numeric observations | Headless fixture verifier | Versioned repository fixture | Test-process lifetime |
|
|
|
|
Side effects:
|
|
|
|
- none;
|
|
- no scene mutation, file/cache write, network send, database access or logging.
|
|
|
|
## Data flow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
ServerFixture[Pinned AzerothCore spawn] --> FixtureVerifier[Golden fixture verifier]
|
|
RawADTFixture[Raw ADT numeric metadata] --> FixtureVerifier
|
|
ClientFixture[Build 12340 observations] --> FixtureVerifier
|
|
FixtureVerifier --> Mapper
|
|
Server[ServerWorldPosition X,Y,Z] -->|identity components| Canonical[CanonicalWowWorldPosition]
|
|
ADT[AdtPlacementPosition X,height,Z] -->|half extent - horizontal| Canonical
|
|
Canonical -->|tileX from Y; tileY from X| Tile[AdtTileCoordinate]
|
|
Canonical -->|north-west edge offsets| Local[AdtTileLocalPosition]
|
|
Local -->|floor offset / chunk size| Chunk[AdtChunkCoordinate]
|
|
Canonical -->|half extent - Y; Z; half extent - X| Godot[GodotWorldPosition]
|
|
ServerYaw[ServerWorldYaw] -->|normalize only| CanonicalYaw[CanonicalWowWorldYaw]
|
|
CanonicalYaw -->|same numeric world angle| GodotYaw[GodotWorldYaw]
|
|
```
|
|
|
|
## Lifecycle/state
|
|
|
|
The module is stateless. Each call reads immutable scalar inputs and returns a
|
|
new value object. There is no initialization, shutdown, cancellation or retry
|
|
state machine.
|
|
|
|
## Main sequence
|
|
|
|
No cross-layer asynchronous sequence occurs inside this module. Producers parse
|
|
or validate their external format first, call the mapper synchronously, and
|
|
then pass only typed results across the next boundary.
|
|
|
|
## Ownership, threading and resources
|
|
|
|
- Value objects own only scalar fields and, for chunks, one immutable tile reference.
|
|
- Callers own returned `RefCounted` references.
|
|
- Methods do not mutate inputs or shared state and are safe for worker use.
|
|
- No Node, RID, file, socket, database or cache resource is acquired.
|
|
|
|
## Errors, cancellation and recovery
|
|
|
|
| Failure | Detection | Behavior | Diagnostic | Recovery |
|
|
|---|---|---|---|---|
|
|
| Tile/chunk outside standard grid | `is_within_map_grid()` | Unclamped indices are preserved | Caller reports source and map context | Reject or apply explicit map policy |
|
|
| Tile-local value outside half-open tile | Consumer boundary validation | Value is preserved | Caller reports source coordinate | Recompute ownership or reject malformed input |
|
|
| Null value object | Static typing/call failure | Programming contract violation | GDScript error with call site | Fix producer; no fallback value |
|
|
| NaN/infinite scalar | Adapter validation | Arithmetic propagates invalid value | Adapter must report source field | Reject malformed external input |
|
|
|
|
There is no cancellation because every conversion is constant-time scalar math.
|
|
|
|
## Configuration and capabilities
|
|
|
|
| Setting/capability | Default | Profile | Runtime mutable | Effect |
|
|
|---|---|---|---|---|
|
|
| Contract version | 2 | All | No | Corrected filename/chunk axes in ADR 0001 |
|
|
| Godot units per WoW yard | 1 | `Blizzlike335` and current tools | No | Preserves current renderer scale |
|
|
| ADT grid | 64 tiles/axis, 16 chunks/tile | WotLK 3.3.5a | No | Defines index and boundary math |
|
|
|
|
## Persistence, cache and migration
|
|
|
|
Production code adds no persisted format, cache or migration. Test schema 1 in
|
|
`coordinate_golden_points.json` persists explicit source provenance, coordinate
|
|
contract version 2, tolerances, source-space values and expected outputs. It
|
|
contains no proprietary bytes, database dump or original-client image. Existing
|
|
dictionaries, native `Vector3` payloads and renderer conversion helpers remain compatible.
|
|
Consumer migration is ordered after this contract and must remove old manual
|
|
conversions only after its producer/consumer tests pass.
|
|
|
|
Any future serialized coordinate must store a schema version and explicit space;
|
|
raw three-number arrays are not an accepted new persistence contract.
|
|
|
|
## Diagnostics and observability
|
|
|
|
- Logs: none in production mapper.
|
|
- Metrics: none; conversion cost is constant and outside frame-budget concern.
|
|
- Debug views: headless contract probe prints one PASS summary.
|
|
- Correlation IDs: supplied by external adapters if an invalid source is reported.
|
|
|
|
## Verification
|
|
|
|
- Unit/contract tests: `src/tools/verify_coordinate_mapper.gd`.
|
|
- Cross-source golden test: `src/tools/verify_coordinate_golden_fixtures.gd`.
|
|
- Integration/E2E: consumer migration and `StreamingFocus` packages remain pending.
|
|
- Fidelity evidence: five build-12340 camera positions from the M00 manifest map
|
|
within `0.002` yard; a pinned AzerothCore human-warrior spawn and one raw MCNK
|
|
header observation independently confirm tile `(32,48)` and chunk `(3,12)`;
|
|
independent reference formulas are recorded in ADR 0001.
|
|
- Performance budgets: constant-time arithmetic; no scene or file access.
|
|
- Manual diagnostics: not required for the pure contract; renderer checkpoints
|
|
are required when consumers migrate.
|
|
|
|
## Extension points
|
|
|
|
- Add typed map IDs around positions without changing axis semantics.
|
|
- Add a format-specific placement-orientation adapter with its own fixtures.
|
|
- Add serialization only with explicit space/version fields and migrations.
|
|
- Add consumer adapters that construct engine-native vectors at their boundary.
|
|
|
|
## Capability status
|
|
|
|
| Capability | Status | Evidence | Gap/next step |
|
|
|---|---|---|---|
|
|
| Canonical/server/Godot position mapping | Implemented | Headless round-trip and five M00 golden points | Migrate producers/consumers |
|
|
| ADT placement mapping | Implemented | Synthetic/direct round-trip fixtures | Compare native parsed placements during migration |
|
|
| ADT tile/local/chunk ownership | Implemented | Center/extent boundaries plus raw `Azeroth_31_49.adt` filename and MCNK direction evidence | Migrate streaming consumers |
|
|
| World-facing yaw mapping | Implemented | Cardinal/wrap round-trip fixtures | Placement Euler remains separate |
|
|
| Scene-free production contract | Implemented | Source boundary and headless test | Add dependency search gate later in M01 |
|
|
| Cross-source coordinate fixture | Implemented | Pinned AzerothCore spawn, raw ADT MCNK metadata and five build-12340 points pass one headless verifier | Add live adapter/renderer integration |
|
|
| TrinityCore populated spawn equivalence | Not verified | The base development schema has no pinned populated row used by this fixture | Pin and verify a TDB snapshot before claiming parity |
|
|
| Visual/server-spawn integration | Planned | M01 target criteria | Route the fixture through migrated adapters and renderer |
|
|
|
|
## Known gaps and risks
|
|
|
|
- Existing native loaders and renderer scripts still contain manual conversions.
|
|
- Contract version 1 briefly transposed ADT filename/chunk axes; version 2 fixes
|
|
the defect before any consumer migration.
|
|
- MDDF/MODF rotation comments and implementations disagree across existing paths;
|
|
this package deliberately does not generalize them into world yaw.
|
|
- Finite-number validation belongs to external format adapters and is not yet implemented.
|
|
- Arithmetic agreement does not prove terrain, placement, camera direction or visual parity.
|
|
- The golden server row is verified against pinned AzerothCore data only; no
|
|
TrinityCore equivalence claim is made without a pinned populated TDB snapshot.
|
|
|
|
## Source map
|
|
|
|
| Path | Responsibility |
|
|
|---|---|
|
|
| `src/domain/coordinates/coordinate_mapper.gd` | Constants and all coordinate-axis conversions |
|
|
| `src/domain/coordinates/*_position.gd` | Immutable typed position values |
|
|
| `src/domain/coordinates/adt_tile_coordinate.gd` | ADT filename tile indices and bounds |
|
|
| `src/domain/coordinates/adt_chunk_coordinate.gd` | MCNK indices and bounds |
|
|
| `src/domain/coordinates/*_yaw.gd` | Immutable typed world-facing yaw values |
|
|
| `src/tools/verify_coordinate_mapper.gd` | Headless fixtures and boundary regressions |
|
|
| `src/tests/fixtures/coordinate_golden_points.json` | Versioned cross-source values, provenance and tolerances |
|
|
| `src/tools/verify_coordinate_golden_fixtures.gd` | Cross-source fixture schema and mapper validation |
|
|
| `docs/adr/0001-canonical-world-coordinates.md` | Normative axes, units, boundaries and rollout decision |
|
|
|
|
## Related decisions and references
|
|
|
|
- ADR: [`../adr/0001-canonical-world-coordinates.md`](../adr/0001-canonical-world-coordinates.md)
|
|
- M00 evidence: [`../M00_FINAL_PAIRED_EVIDENCE.md`](../M00_FINAL_PAIRED_EVIDENCE.md)
|
|
- Architecture: [`../ARCHITECTURE.md`](../ARCHITECTURE.md)
|
|
- Testing rules: [`../TESTING.md`](../TESTING.md)
|