104 lines
4.5 KiB
Markdown
104 lines
4.5 KiB
Markdown
# M03-RND-TERRAIN-LOD-PLANNER-001 — Pure terrain chunk LOD planner
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-TERRAIN-LOD-PLANNER-001:sindo-main-codex:2026-07-18 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-terrain-chunk-lod-planner`
|
|
- Lease expires UTC: 2026-07-18
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract chunk-level terrain LOD desired-state calculation from the streamer into
|
|
a scene-free `TerrainChunkLodPlanner` with immutable policy and typed focus input.
|
|
|
|
## Non-goals
|
|
|
|
- Move chunk/tile queues, loaded state, Mesh/Node/RID creation or budget drains.
|
|
- Change radii, chunk size, threshold inclusivity, priority sorting or tile LOD policy.
|
|
- Normalize/reorder custom radii or reinterpret negative values.
|
|
- Move ADT parsing, quality cache/tasks, materials or ground query.
|
|
- Add dependencies, persistence, workers or mark terrain extraction complete.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/terrain/terrain_chunk_lod_policy.gd`,
|
|
`src/render/terrain/terrain_chunk_lod_planner.gd`,
|
|
`src/tools/verify_terrain_chunk_lod_planner.gd`,
|
|
`docs/modules/terrain-chunk-lod-planner.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`docs/modules/world-renderer.md`, `docs/modules/README.md`, `RENDER.md`,
|
|
`targets/03-renderer-facade.md`
|
|
- Generated/ignored: `.godot`, native DLL, generated resources, caches and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Input: ADT chunk adapter records, immutable `GodotWorldPosition`, immutable
|
|
enabled/radii/chunk-size policy
|
|
- Output: detached Dictionary mapping source chunk index to LOD `0`, `1` or `2`
|
|
- Formula: horizontal distance to `origin + half chunk`; inclusive squared thresholds
|
|
- Disabled policy and empty/sparse chunks return absent entries exactly as before
|
|
- Queue/cache/schema/coordinate versions: unchanged
|
|
|
|
## Dependencies
|
|
|
|
- Requires: integrated terrain cache slice master `ea08b8e`
|
|
- Blocks: broader terrain service extraction and dependency/performance acceptance
|
|
- External state: none; tests use synthetic chunk adapter records
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated center/boundary/outside/sparse/disabled/custom-radius and
|
|
bounded timing verifier; loader source boundary; facade/cache/internal-access/
|
|
manifest/shutdown/scheduler/streaming planner and repository gates
|
|
- Fidelity evidence: extracted formulas and all seven baseline plans remain unchanged
|
|
- Performance budget: bounded linear scan over at most the ADT chunk record count;
|
|
no Node, Resource, RID, task, cache entry or allocation framework
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline API docs for policy/planner
|
|
- New module spec with inputs/outputs, data-flow, lifecycle, sequence, ownership,
|
|
failure, performance and source map
|
|
- World renderer/module registry/`RENDER.md` updates
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names: `TerrainChunkLodPolicy`, `TerrainChunkLodPlanner`
|
|
- Simplest solution: immutable scalar policy plus one pure linear planner
|
|
- Rejected complexity: generic spatial index, quadtree, callback strategy,
|
|
normalized profile model or queue ownership
|
|
- Unavoidable complexity: raw chunk dictionaries remain at the ADT adapter boundary
|
|
- Measured optimization evidence: verifier records bounded High-like planning time
|
|
|
|
## Status
|
|
|
|
- State: accepted
|
|
- Done: immutable policy, pure planner, both loader call sites, regressions and docs
|
|
- Next: asset-backed performance acceptance and further terrain-service extraction later in M03
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-TERRAIN-LOD-PLANNER-001:eb94cfc -->
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-TERRAIN-LOD-PLANNER-001:f36fabb -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `eb94cfc` (`refactor(M03): extract terrain chunk LOD planner`)
|
|
- Results: dedicated contract PASS (`cases=7`, `iterations=250`, `12.726 ms`);
|
|
cache/facade/internal-access/manifest/shutdown/scheduler/streaming-focus/
|
|
streaming-planner/ground/terrain-query/coordinate regressions PASS; editor parse
|
|
has no script errors; documentation and coordination gates PASS; checkpoint
|
|
dry-run planned `7/7` entries with expected missing-private-corpus diagnostics
|
|
- Remaining risks: asset-backed p95/p99 and visual acceptance remain pending;
|
|
terrain state, queue, quality-upgrade and finalization ownership remains in loader
|
|
- Documentation updated: `terrain-chunk-lod-planner.md`, module registry,
|
|
`world-renderer.md`, `RENDER.md`, inline public API documentation and data-flow,
|
|
lifecycle and sequence diagrams
|
|
- Integration: accepted in master merge `f36fabb`; post-merge planner, facade,
|
|
internal-access and manifest gates passed
|