112 lines
5.3 KiB
Markdown
112 lines
5.3 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: ready-for-review
|
|
- Done: added renderer-owned typed sample, facade query/snapshot, migrated terrain
|
|
probe, expanded internal-access/coordinate gates and updated module docs
|
|
- Next: M03 integrator reviews and merges `b697a89` plus cold-start fix `9408d88`
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-FACADE-GROUND-QUERY-001:9408d88 -->
|
|
|
|
## Handoff
|
|
|
|
- Commits: implementation `b697a89`; cold-start fix `9408d88`
|
|
- Results: `WorldRenderFacade` delegates loaded-mesh ground sampling and returns
|
|
renderer-owned `RenderedGroundSample`; detached diagnostic snapshots preserve
|
|
the probe report while hiding queue/tile/Mesh/Node references. Gameplay remains
|
|
on the independent M02 `TerrainQuery` composition.
|
|
- Verification: facade `delegation=5 ground_contract=2 runtime_scenes=2 tools=3`;
|
|
cold rendered-ground value `contract=3` from an empty Godot class cache;
|
|
internal access `private_symbols=43 gameplay=7 editor_sources=9 renderer_tools=1`;
|
|
terrain query contracts passed; coordinate boundary `files=113 consumers=5`;
|
|
renderer manifest `7/7`; shutdown ownership, scheduler/planner, coordination,
|
|
documentation and diff gates passed.
|
|
- Fidelity: the probe's 5000-unit ray height, 3x3 tile search, highest-hit choice,
|
|
readiness fields and `2/5/10/20/40` nearby fallback moved unchanged. No terrain
|
|
geometry, streaming, cache, material, placement or visual rule changed. No
|
|
build-12340 parity claim is added.
|
|
- External/local inputs: ignored native DLL and generated ADT resource scripts
|
|
were copied from master only for editor/streamer parse and then removed.
|
|
Proprietary extracted world data was unavailable, producing expected degraded diagnostics.
|
|
- Remaining risks: triangle-mesh generation is on-demand/main-thread and diagnostic;
|
|
it is unsuitable for per-physics-frame gameplay; exact asset-backed probe output
|
|
still depends on local corpus readiness; environment/entity facade contracts remain.
|
|
- Documentation: inline facade/loader/value API; world-renderer API/data-flow/
|
|
sequence/ownership/recovery/capability/source map; terrain-query authority
|
|
clarification and renderer implementation notes updated.
|