sindoring
a45d521567
Work-Package: M02-GMP-TERRAIN-QUERY-001 Agent: sindo-main-codex Tests: terrain query, player input and movement regressions; asset-free scene; renderer dry-run; coordinate, streaming, documentation and coordination gates Fidelity: preserves existing ADT outer-grid interpolation and player ground snap; build-12340 collision parity remains unverified
85 lines
3.4 KiB
Markdown
85 lines
3.4 KiB
Markdown
# M02-GMP-TERRAIN-QUERY-001 — Player terrain query boundary
|
|
|
|
<!-- OPENWC_CLAIM:M02-GMP-TERRAIN-QUERY-001:sindo-main-codex:2026-07-16 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M02
|
|
- Program: GMP/RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m02-terrain-query`
|
|
- Lease expires UTC: 2026-07-16
|
|
- Integrator: M02 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Introduce a typed `TerrainQuery` boundary and move ADT loading, caching, chunk
|
|
selection and height interpolation out of `ThirdPersonWowController` without
|
|
changing current spawn/ground-snap behavior.
|
|
|
|
## Non-goals
|
|
|
|
- Change ADT topology, coordinate formulas, terrain mesh or renderer caches.
|
|
- Add physics collision, slopes, water, jump/fall/swim or server movement.
|
|
- Reuse the streaming renderer cache before its public terrain-query contract exists.
|
|
- Extract camera or character presentation.
|
|
- Mark M02 complete or edit its checklist/Evidence.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/gameplay/terrain/`, `src/tools/verify_terrain_query.gd`,
|
|
`docs/modules/terrain-query.md`, this claim
|
|
- Shared/hotspots: `src/scenes/player/third_person_wow_controller.gd`,
|
|
`src/tools/verify_player_input.gd`,
|
|
`src/tools/verify_coordinate_conversion_boundaries.gd`,
|
|
`docs/modules/local-player-movement.md`,
|
|
`docs/modules/README.md`
|
|
- Generated/ignored: local `.godot`, native DLL, generated ADT resources and renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Public API: `TerrainQuery.sample_ground_height(GodotWorldPosition)` returning
|
|
immutable `TerrainGroundSample`
|
|
- Production adapter: `AdtTerrainQuery` with owned per-tile parse cache
|
|
- Test/data-source seam: optional ADT tile loader callable at construction
|
|
- Coordinate contract version, ADT format, renderer cache and persistence: unchanged
|
|
- Consumers: current player scene; future movement/collision policies
|
|
|
|
## Dependencies
|
|
|
|
- Requires: merged movement controller on master `5206c42`
|
|
- Blocks: camera/presentation extraction from the player hotspot
|
|
- External state: production uses existing native `ADTLoader`; synthetic tests need no proprietary data
|
|
|
|
## Verification
|
|
|
|
- Commands: synthetic height/cache/failure verifier, player input/movement
|
|
regressions, asset-free scene, coordinate/StreamingFocus gates, renderer dry-run
|
|
and repository gates
|
|
- Fixtures: synthetic 145-height chunk payload and injected flat terrain query
|
|
- Fidelity evidence: preserves existing outer-grid bilinear interpolation,
|
|
spawn ground offset and per-tick snap formula only
|
|
- Performance budget: one cached tile lookup and local interpolation per ground query;
|
|
no new I/O after first tile load
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs for query, sample and ADT adapter
|
|
- Terrain-query module spec with inputs/outputs, data-flow, cache lifecycle and sequence diagrams
|
|
- Updated movement/coordinate consumer boundaries, source maps and module registry
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names: `TerrainQuery`, `TerrainGroundSample`, `AdtTerrainQuery`
|
|
- Simplest approach: one narrow query contract, one typed result and one existing-format adapter
|
|
- Rejected complexity: general collision framework, terrain service locator and renderer-cache coupling
|
|
- Unavoidable complexity: ADT 145-height layout and chunk lookup stay isolated in adapter
|
|
- Measured optimization evidence: existing per-tile cache retained; no new optimization
|
|
|
|
## Status
|
|
|
|
- State: active
|
|
- Done: claim and isolated worktree from updated master
|
|
- Next: implement contract/adapter, migrate player, test and document
|
|
- Blocked by:
|