LOD GPU roadmap Phase 1: remove CPU and submission hot spots

[MichaelFisher1997]

Goal

Capture low-risk gains before adding GPU compute. Keep policy, persistence, and procedural generation on CPU while eliminating unnecessary scans, locks, I/O, and draw submission.

Depends on

Phase 0 profiling baselines.

Parallel workstreams

Visibility and coverage

• Frustum/radius reject before isCoveredByChunks.
• Replace per-region full-chunk enumeration with cached/coarse coverage data.
• Build visibility once per frame and share it between terrain and water.
• Measure candidates/reject reasons by LOD level.

Lifecycle and threading

• Replace repeated HashMap scans/sorts with state queues, counters, and bounded priority structures.
• Snapshot/pin immutable source data, mesh outside the manager lock, and publish with token/version validation.
• Move cache reads, deserialization, dirty serialization, and writes off the update thread.
• Reconcile pause/unpause states for jobs cleared from the queue.

Draw submission

• Production-harden and default-enable existing terrain MDI where supported.
• Add pooled/indirect batching for LOD water.
• Keep a tested direct-draw fallback.

Far-detail density

• Benchmark reduced LOD3/4 sample grids and cheaper representative sampling.
• Reuse coarse parent samples while refining children.
• Disable or aggregate vegetation detail where it is sub-pixel.

Relevant code

• modules/world-lod/src/lod_renderer.zig
• modules/world-lod/src/lod_manager_generation_ops.zig
• modules/world-lod/src/lod_manager_cache_ops.zig
• modules/world-lod/src/lod_mesh.zig
• modules/world-lod/src/lod_scheduler.zig
• modules/worldgen-overworld-v2/src/lod_sampling.zig

CPU/GPU decision

Scheduling, persistence, procedural sampling, and coarse visibility remain CPU work. The GPU receives batched drawing, not generation, in this phase.

Acceptance criteria

• No synchronous disk I/O on the frame/update path.
• Meshing does not hold the global manager lock for its full duration.
• Terrain and water do not independently repeat identical visibility/coverage work.
• MDI reduces LOD submission/draw overhead without visual regressions; fallback remains functional.
• Benchmarks demonstrate lower p95/p99 CPU frame time, not only higher average FPS.

[github-actions]

Classification: Feature Request (enhancement + perf/rendering).

Umbrella context. This is one of six sibling roadmap issues for the LOD GPU track (#917, #918, #919, #920, #921, #922). It depends on Phase 0 profiling baselines (#921, still OPEN), so the acceptance criteria (p95/p99 attribution) cannot be fully validated until that lands. I did not find an umbrella issue linking them — worth creating one if you want a single tracking entry point.

Existing scaffolding the checklist can lean on. A few of the bullet items are already partially implemented behind flags or counters rather than fully wired:

• Terrain MDI plumbing already exists in modules/world-lod/src/lod_renderer.zig (enable_mdi, instance_buffers, indirect_buffers, renderIndirectBatches), but it is default-disabled via ZIGCRAFT_ENABLE_LOD_MDI (line ~143). "Default-enable where supported" is therefore mostly a config/validation flip plus the overflow paths at lines 261/270.
• Frustum reject before isCoveredByChunks is partially in place: isRegionInFrustum (line ~669) is called at line ~409, but only after the per-region full-chunk coverage walk at line ~385. Reordering those two is a localized, low-risk win.
• Per-LOD reject accounting already exposes frustum_culled, chunk_cov, range via LOD_RENDER_DIAG (line ~459); "measure candidates/reject reasons by LOD level" mainly requires extending that log line.
• Terrain vs. water already split via LODRenderLayer (lod_upload_queue.zig:76), but each layer independently walks regions inside collectVisibleMeshes. Sharing visibility results is a refactor of that single function.

Scope check — recommend splitting into sub-issues. The four workstreams are cleanly independent and each touches a different subsystem (renderer, scheduler, manager lock/cache, worldgen sampling). I'd break this issue into four sub-issues, each owning one workstream and 2–4 checkboxes, plus a tracking issue for the acceptance criteria:

1. [Phase 1.A] Visibility and coverage — lod_renderer.zig reorder + visibility sharing + per-LOD reject metrics. Lowest risk; can land first and unblock acceptance criterion feat: voxel engine with worldgen, async streaming, and render stability #3.
2. [Phase 1.B] Lifecycle and threading — lod_manager_generation_ops.zig, lod_manager_cache_ops.zig, lod_scheduler.zig. Largest design surface; touches the manager lock and queueing. Addresses criteria Roadmapv3 #1 and feat: implement layered noise worldgen with multi-noise biomes #2. Highest value but needs its own design doc.
3. [Phase 1.C] Draw submission — default-enable terrain MDI, add pooled/indirect batching for water, keep fallback tested. Touches lod_renderer.zig, lod_vertex_pool.zig, and adds new shader/descriptor wiring for water MDI.
4. [Phase 1.D] Far-detail density — worldgen-overworld-v2/src/lod_sampling.zig plus lod_vegetation.zig. Benchmark-driven; results should feed back into config defaults rather than code.

Splitting lets each sub-issue get its own PR review and benchmark run, and lets 1.A land without waiting on the lock/caching redesign in 1.B. Happy to draft any of them if useful.

One missing detail. The acceptance criteria mention p95/p99 CPU frame time, but it isn't clear which zig build benchmark preset (low/medium/high/ultra/extreme) and which camera scenarios (stationary / traversal / turn / teleport) should be the gating reference. If Phase 0 (#921) doesn't pin those, it would be good to record the Phase 1 ones here so reviewers know what "lower p95/p99" means in numbers.

[github-actions]

Posted analysis comment on #920: classified as Feature Request, mapped the four workstreams to existing scaffolding in lod_renderer.zig, and recommended splitting into four sub-issues (1.A visibility, 1.B lifecycle/locking, 1.C draw submission, 1.D far-detail density) so each can land and be benchmarked independently against the Phase 0 (#921) baselines. Also flagged the missing p95/p99 reference scenario in the acceptance criteria.

opencode session  |  github run