116 lines
5.4 KiB
Markdown
116 lines
5.4 KiB
Markdown
# M03-RND-TERRAIN-CACHE-SERVICE-001 — Terrain quality mesh cache service
|
|
|
|
<!-- OPENWC_CLAIM:M03-RND-TERRAIN-CACHE-SERVICE-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-quality-cache`
|
|
- Lease expires UTC: 2026-07-18
|
|
- Integrator: M03 milestone integrator
|
|
|
|
## Outcome
|
|
|
|
Extract the full-quality terrain revisit Mesh cache, its LRU ownership and
|
|
source-admission rules from `StreamingWorldLoader` into a small scene-free
|
|
`TerrainQualityMeshCache`, preserving all call sites and observable behavior.
|
|
|
|
## Non-goals
|
|
|
|
- Move ADT parsing, tile state, quality-upgrade tasks/results or SceneTree/RID finalization.
|
|
- Change cache capacity defaults, quality profiles, source priority or cache formats.
|
|
- Cache control-splat/splat meshes that the current loader deliberately rejects.
|
|
- Extract chunk LOD, terrain material building, ground query or other asset services.
|
|
- Add dependencies, persistence, background work or mark the terrain service complete.
|
|
|
|
## Paths
|
|
|
|
- Exclusive: `src/render/terrain/terrain_quality_mesh_cache.gd`,
|
|
`src/tools/verify_terrain_quality_mesh_cache.gd`,
|
|
`docs/modules/terrain-quality-mesh-cache.md`, this claim
|
|
- Shared/hotspots: `src/scenes/streaming/streaming_world_loader.gd`,
|
|
`src/tools/verify_render_runtime_cache_shutdown.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
|
|
|
|
- Public service API: `store`, `restore`, `clear`, detached `diagnostic_snapshot`
|
|
- Entry: tile key, retained Mesh reference and source string
|
|
- Admission: non-empty key, non-null Mesh, source other than
|
|
`control_splat_cache`, `splat_cache` or `splat`
|
|
- LRU: successful restore touches newest; store touches then trims oldest to
|
|
`max(0, capacity)`; invalid restored records are removed
|
|
- Persistence/cache format: none; session-memory ownership only
|
|
|
|
## Dependencies
|
|
|
|
- Requires: integrated facade contracts master `61bad09`
|
|
- Blocks: later terrain service extraction and cache/finalization acceptance audit
|
|
- External state: none; tests use synthetic ArrayMesh references
|
|
|
|
## Verification
|
|
|
|
- Commands: dedicated cache contract/LRU/ownership regression; streamer source
|
|
boundary; shutdown/facade/internal-access/manifest/planner/scheduler and repository gates
|
|
- Fixtures: admission/rejection, replacement, LRU touch/eviction, zero/negative
|
|
capacity, invalid record cleanup, clear and detached diagnostics
|
|
- Fidelity evidence: same sources/capacity/call sites; all seven baseline plans unchanged
|
|
- Performance budget: dictionary lookup plus bounded single-entry LRU operations;
|
|
no Node, task, file, cache serialization or RID creation
|
|
|
|
## Documentation deliverables
|
|
|
|
- Inline public API docs: store/restore/clear/diagnostics and ownership
|
|
- Module specification: new terrain quality mesh cache specification
|
|
- Data-flow diagram: upgrade result through cache to revisit state
|
|
- Sequence/state/dependency diagrams: store/restore/evict/reset and failure paths
|
|
- Source map/status updates: module registry, world renderer and `RENDER.md`
|
|
|
|
## Simplicity and naming
|
|
|
|
- Important names introduced: `TerrainQualityMeshCache`
|
|
- Simplest considered solution: one RefCounted with dictionary plus ordered tile-key array
|
|
- Rejected complexity/abstractions: generic cache framework, weak references,
|
|
callbacks, Resource cache integration, background eviction or persistence
|
|
- Unavoidable complexity and justification: Mesh references must survive unloaded
|
|
tile state while LRU keeps revisit memory bounded
|
|
- Measured optimization evidence: exact ownership extraction, no optimization claim
|
|
|
|
## Status
|
|
|
|
- State: ready-for-review
|
|
- Done: scene-free cache ownership/LRU extraction, loader adapter migration,
|
|
contract regression and module documentation
|
|
- Next: M03 integrator reviews and merges `97480e0`
|
|
- Blocked by:
|
|
|
|
<!-- OPENWC_HANDOFF:READY:M03-RND-TERRAIN-CACHE-SERVICE-001:97480e0 -->
|
|
|
|
## Handoff
|
|
|
|
- Commit: `97480e0`
|
|
- Results: `TerrainQualityMeshCache` now owns retained full-quality Mesh
|
|
references, source admission and oldest-to-newest LRU. The loader retains only
|
|
restore-to-state, store-after-upgrade and clear lifecycle adapters.
|
|
- Verification: cache `contract_cases=15 loader_calls=3`; facade/entity/ground/
|
|
terrain regressions; internal access `private_symbols=42 gameplay=7
|
|
editor_sources=9 renderer_tools=1`; manifest `7/7`; shutdown; scheduler
|
|
`20000` iterations; planner `250` iterations; focus; editor parse; dry-run;
|
|
coordination, documentation and diff gates passed.
|
|
- Fidelity: `baked_full` revisit retention, three excluded splat sources, LRU
|
|
touch/trim, profile capacities and all call sites remain unchanged. All seven
|
|
checkpoint plans remain valid. No visible or build-12340 parity claim is added.
|
|
- External/local inputs: ignored native DLL and generated ADT scripts supported
|
|
parse/dry-run only; missing proprietary ADT/DBC/character data produced expected diagnostics.
|
|
- Remaining risks: entry count does not measure Mesh bytes; ordered-array touch
|
|
remains linear; asset-backed revisit flash, memory and p95/p99 evidence remain pending;
|
|
terrain build/tasks/state/finalization are still monolithic.
|
|
- Documentation updated: new terrain cache API/input-output/data-flow/lifecycle/
|
|
sequence/ownership/failure/configuration/migration/diagnostic/source-map spec;
|
|
world renderer, registry and `RENDER.md` updated.
|