105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
# M03-RND-TERRAIN-CHUNK-QUEUE-001 — Pure terrain chunk geometry queue planner
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-TERRAIN-CHUNK-QUEUE-001:sindo-main-codex:2026-07-19 -->
|
|
|
|
## Ownership
|
|
|
|
- Target: M03
|
|
- Program: RND
|
|
- Owner/Agent ID: sindo-main-codex
|
|
- Branch: `work/sindo-main-codex/m03-terrain-chunk-queue`
|
|
- Lease expires UTC: 2026-07-19
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract chunk-geometry create/remove desired-operation calculation from the
|
|
streamer into a scene-free `TerrainChunkGeometryQueuePlanner`.
|
|
|
|
## Non-goals
|
|
|
|
- Move queue storage/drains, render budgets, tile-LOD queues or async tasks.
|
|
- Move chunk Mesh/Node/RID creation/removal or terrain state ownership.
|
|
- Change removal-first execution, nearest-first create order or LOD selection.
|
|
- Change coordinate conversions, radii, cache formats or quality profiles.
|
|
- Add dependencies or mark the broad terrain service checklist complete.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/terrain/terrain_chunk_geometry_queue_planner.gd`,
|
|
`src/tools/verify_terrain_chunk_geometry_queue_planner.gd`,
|
|
`docs/modules/terrain-chunk-geometry-queue-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 ADT resources, caches and
|
|
proprietary renderer corpus
|
|
|
|
## Contracts and data
|
|
|
|
- Input: loader-owned tile-state read model plus immutable `GodotWorldPosition`
|
|
- Output: fresh create/remove request arrays; planner retains no queue state
|
|
- Removal: current chunks absent from desired state, or all current chunks while
|
|
tile LOD is desired
|
|
- Creation: missing or LOD-mismatched chunks, sorted by origin XZ distance
|
|
- Queue/cache/schema/coordinate versions: unchanged
|
|
|
|
## Dependencies
|
|
|
|
- Requires: integrated terrain LOD planner master `b568768`
|
|
- Blocks: broader terrain service extraction and dependency/performance acceptance
|
|
- External state: none; tests use synthetic tile/chunk dictionaries
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated removal/create/mismatch/tile-fallback/sparse/order and
|
|
bounded timing verifier; loader source boundary; facade/cache/LOD/internal-access/
|
|
manifest/shutdown/scheduler/streaming planner and repository gates
|
|
- Fidelity evidence: extracted branch/order/distance rules and loader drain order
|
|
- Performance budget: bounded linear planning plus existing create sort; no engine
|
|
resource, task, cache or persistent allocation framework
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline planner API documentation
|
|
- 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 name: `TerrainChunkGeometryQueuePlanner`
|
|
- Simplest solution: one stateless planner returning two fresh arrays
|
|
- Rejected complexity: generic operation graph, queue class, callback strategy,
|
|
spatial index or ownership transfer
|
|
- Unavoidable complexity: raw dictionaries remain at the loader/ADT adapter boundary
|
|
- Measured optimization evidence: bounded synthetic multi-tile verifier
|
|
|
|
## Status
|
|
|
|
- State: accepted
|
|
- Done: pure planner, loader queue adoption, semantic/timing regressions and docs
|
|
- Next: asset-backed performance acceptance and further terrain-service extraction later in M03
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-TERRAIN-CHUNK-QUEUE-001:f800e11 -->
|
|
<!-- OPENWC_INTEGRATION:ACCEPTED:M03-RND-TERRAIN-CHUNK-QUEUE-001:24aef13 -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `f800e11` (`refactor(M03): extract terrain chunk queue planner`)
|
|
- Results: dedicated contract PASS (`cases=8`, `iterations=100`, `235.096 ms`);
|
|
LOD/cache/facade/internal-access/manifest/shutdown/scheduler/streaming/focus/
|
|
ground/terrain-query/coordinate regressions PASS; internal inventory remains
|
|
`42`; editor parse has no script errors; documentation/coordination/diff gates
|
|
PASS; checkpoint dry-run planned `7/7` entries with expected missing-private-
|
|
corpus diagnostics
|
|
- Remaining risks: planner adds a second linear tile-state pass; asset-backed
|
|
p95/p99 and visual acceptance remain pending; queue drains, terrain state and
|
|
Mesh/Node/RID finalization remain loader-owned
|
|
- Documentation updated: `terrain-chunk-geometry-queue-planner.md`, module
|
|
registry, `world-renderer.md`, `RENDER.md`, inline API documentation and
|
|
data-flow/lifecycle/sequence diagrams
|
|
- Integration: accepted in master merge `24aef13`; post-merge planner,
|
|
internal-access, facade and manifest gates passed
|