82 lines
3.4 KiB
Markdown
82 lines
3.4 KiB
Markdown
# M03-RND-FACADE-GROUND-QUERY-001 — Rendered ground query facade
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-FACADE-GROUND-QUERY-001:sindo-main-codex:2026-07-18 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-facade-ground-query`
|
|
- Lease expires UTC: 2026-07-18
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Expose typed ground-height sampling and a detached readiness diagnostic through
|
|
`WorldRenderFacade`, using already loaded render terrain meshes, and migrate the
|
|
terrain-height probe away from direct streamer state/queue access.
|
|
|
|
## Non-goals
|
|
|
|
- Replace the M02 gameplay-owned `TerrainQuery`/`AdtTerrainQuery` composition.
|
|
- Make rendered mesh sampling authoritative for movement, collision or server state.
|
|
- Add slopes, holes, liquid, WMO/M2 collision or async query callbacks.
|
|
- Change terrain meshes, streaming policy, queue order, cache formats or visuals.
|
|
- Complete environment/entity-visual facade contracts or mark M03 complete.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: this claim
|
|
- Shared/hotspots: `src/render/world_render_facade.gd`,
|
|
`src/scenes/streaming/streaming_world_loader.gd`,
|
|
`src/tools/probe_render_terrain_height.gd`,
|
|
`src/tools/verify_world_render_facade.gd`,
|
|
`src/tools/verify_renderer_internal_access.gd`, `docs/modules/world-renderer.md`,
|
|
`docs/modules/terrain-query.md`, `RENDER.md`, `targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated ADT resource scripts,
|
|
extracted renderer corpus and probe reports
|
|
|
|
## Contracts and data
|
|
|
|
- Input: immutable `GodotWorldPosition` in Godot world units
|
|
- Output: renderer-owned immutable `RenderedGroundSample` plus optional detached diagnostic Dictionary
|
|
- Sampling source: loaded quality or tile-LOD Mesh and its live tile transform
|
|
- M02 ADT query cache, renderer cache versions and coordinate contracts: unchanged
|
|
|
|
## Dependencies
|
|
|
|
- Requires: M02 terrain query contract and integrated M03 facade/access gate `53d84cc`
|
|
- Blocks: removal of renderer diagnostic internal-access exception and later terrain service extraction
|
|
- External state: asset-backed probe is optional; contract tests use a facade double
|
|
|
|
## Verification
|
|
|
|
- Commands: facade query/snapshot isolation contract, internal-access gate,
|
|
terrain-query regression, focus/coordinate/manifest/shutdown regressions and repository gates
|
|
- Fixtures: available/unavailable sample, detached diagnostic, probe source migration
|
|
- Fidelity evidence: mesh ray/nearest fallback algorithm moves unchanged from the probe
|
|
- Performance budget: on-demand diagnostic query only; no per-frame query added
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline facade/streamer API docs
|
|
- World-renderer API/data-flow/sequence/ownership/recovery/source-map updates
|
|
- Terrain-query backend status/ownership clarification and renderer implementation note
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names: `sample_ground_height`, `renderer_ground_query_snapshot`
|
|
- Simplest approach: one typed facade query over one existing diagnostic read model
|
|
- Rejected complexity: duplicate ADT cache, physics service, callback bus, query node,
|
|
generic spatial interface or new dependency
|
|
- Unavoidable complexity: triangle-mesh ray query retains the existing bounded
|
|
nearby fallback for seam/edge diagnostic behavior
|
|
|
|
## Status
|
|
|
|
- State: active
|
|
- Done: facade/backend ownership and diagnostic compatibility contract defined
|
|
- Next: move sampling behind loader/facade, migrate probe, add tests/docs
|
|
- Blocked by:
|