[Epic] Build a GPU-driven distant-terrain LOD pipeline

[MichaelFisher1997]

Objective

Evolve ZigCraft distant terrain into a measured hybrid CPU/GPU architecture capable of approaching Distant Horizons-like quality and scale without assuming that every workload belongs on GPU.

Architectural assessment

The current system is predominantly CPU-driven: procedural sampling, mesh generation, hierarchy scheduling, visibility/coverage checks, streaming, persistence, and default direct draw submission occur on CPU. The GPU mainly transforms and shades uploaded conventional vertices. Terrain MDI exists but is optional, while the LOD GPU-culling switch currently falls back to CPU behavior.

The architecture can improve substantially without a rewrite through visibility, threading, MDI, transfer, and synchronization work. Reaching genuinely large horizons with high quality likely requires the Phase 4 representation change: compact far-terrain tiles plus GPU-driven visibility/submission. Procedural generation, persistence, edits, and policy should remain CPU-owned unless measurements prove otherwise.

Current responsibility map

Work	Current owner	Target owner
Procedural terrain sampling	CPU workers	CPU workers, cheaper/reused for far levels
Persistence and edit provenance	CPU/update path	Async CPU I/O/workers
Region hierarchy and scheduling	CPU	CPU
Mesh construction	CPU workers	CPU near LOD; GPU-friendly compact representation for far LOD
Frustum/coverage culling	CPU, repeated by layer	CPU broad policy + GPU high-cardinality culling
Draw submission	CPU direct draws; optional terrain MDI	GPU-compacted indirect terrain and water
Uploads/lifetime	CPU staging with global idle paths	Async ring staging + fence/timeline retirement
Terrain/water shading	GPU	GPU, with cheaper far-water/material paths

Ranked concerns

1. Repeated CPU visibility and chunk-coverage work, including terrain/water duplication.
2. Direct per-region submission because MDI is disabled by default and water remains direct.
3. Dense CPU-generated far meshes, expensive representative sampling, and large vertex uploads.
4. Repeated global state scans/sorts and long-lived manager lock participation.
5. Synchronous cache activity on the update path.
6. vkDeviceWaitIdle during eviction/pool operations and avoidable upload copies.
7. Incomplete memory accounting and unmanaged pool slack/shadow allocations.
8. No production GPU culling/indirect-command compaction.
9. Far-water shader cost and fragment-discard handoff waste.

Phased delivery

• LOD GPU roadmap Phase 0: establish profiling and quality baselines #921 — Phase 0: profiling and quality baselines
• LOD GPU roadmap Phase 1: remove CPU and submission hot spots #920 — Phase 1: CPU visibility, threading, density, and MDI quick wins
• LOD GPU roadmap Phase 2: asynchronous transfers, lifetime, and memory #919 — Phase 2: asynchronous transfers, resource lifetime, and memory
• LOD GPU roadmap Phase 3: GPU culling and indirect command generation #918 — Phase 3: GPU culling and indirect command generation
• LOD GPU roadmap Phase 4: compact GPU-rendered far-terrain tiles #917 — Phase 4: compact GPU-rendered far-terrain tiles
• LOD GPU roadmap Phase 5: quality, scale, and production hardening #922 — Phase 5: quality, scale, and production hardening

Dependency graph

Phase 0 instrumentation
 ├─ Phase 1 CPU/MDI improvements ─────┐
 ├─ Phase 2 transfer/lifetime ────────┼─ Phase 3 GPU culling
 └─ visual + memory baselines ────────┘          │
                                                  ▼
                                  Phase 4 compact far tiles
                                                  │
                                                  ▼
                                  Phase 5 quality/hardening

Within each phase, workstreams marked parallel may be developed concurrently. Shared RHI/Vulkan contract changes and resource-lifetime changes must merge sequentially behind explicit interfaces.

Global constraints

• Optimize based on p95/p99 and attributed timings, not average FPS alone.
• Compare CPU and GPU paths at realistic candidate counts; small jobs may remain faster on CPU.
• Avoid GPU readback in generation/streaming loops.
• Maintain feature-gated fallbacks for hardware lacking required indirect/timeline capabilities.
• Never trade hidden VRAM growth or synchronization hitches for apparent CPU gains.
• Validate visual stability, edits, persistence, cancellation, and memory pressure alongside speed.
• Mesh shaders are optional research, not a prerequisite; compute + conventional indirect rendering comes first.

Epic completion criteria

• CPU/GPU responsibilities match the target map and are backed by measurements.
• Large-horizon traversal stays within agreed p95/p99 CPU, GPU, RAM, and VRAM budgets.
• Normal streaming has no global device-idle synchronization.
• GPU culling and indirect submission have validated CPU fallbacks.
• Far LOD upload and geometry memory scale with compact tiles rather than expanded vertices.
• Automated benchmark and visual suites prevent performance, seam, transition, and handoff regressions.

Validation matrix

For every phase, test stationary views, forward traversal, rapid rotation, teleport/eviction pressure, edits, save/reload, and long-running low-memory scenarios. Use nix develop --command for all builds/tests and bounded headless graphics runs.

[github-actions]

Epic classification: Feature Request (architectural roadmap, not a bug). The scope is already appropriately decomposed into the 6 phase sub-issues (#917–#922) with a clean dependency graph, so no further splitting is needed — each phase is independently mergeable behind the documented interfaces.

A few observations that should help shape implementation order:

1. Phase 0 (LOD GPU roadmap Phase 0: establish profiling and quality baselines #921) is the real gating work. Everything else is ungrounded without LOD-specific timings and memory attribution. There is already an LODStats struct in modules/world-lod/src/lod_stats.zig carrying state counts, queue depths, vertex totals, and store/cache hits; Phase 0 should extend it (rather than create a parallel metric system) with per-stage CPU scopes, GPU timestamp pairs for the LOD opaque/water passes, lock-hold histograms, and vkDeviceWaitIdle call sites. That keeps Phase 1/2/3 changes measurable against a consistent baseline.

2. Phase 1 (LOD GPU roadmap Phase 1: remove CPU and submission hot spots #920) is the cheapest, highest-confidence win. It is largely orthogonal to the RHI/Vulkan contract and unblocks the "is this even fast enough?" question for Phase 3/4. Recommend landing it on dev first, with the MDI-default toggle behind the existing feature flag so it can be A/B compared against the current direct submission path.

3. Phase 2 (LOD GPU roadmap Phase 2: asynchronous transfers, lifetime, and memory #919) needs to land before Phase 3 (LOD GPU roadmap Phase 3: GPU culling and indirect command generation #918) for the GPU culling path to avoid stalling the ring. The shared RHI resource-lifetime contract change in Phase 2 should be merged as its own PR with the new interfaces stubbed out (and the existing idle paths exercised in tests), so Phase 3 can build the indirect-command generation against the real retirement mechanism rather than a temporary one.

4. Phase 4 (LOD GPU roadmap Phase 4: compact GPU-rendered far-terrain tiles #917) is the only phase that changes representation. It should be treated as research-grade with feature gating from day one and a fully validated CPU fallback, per the global constraint about hardware lacking indirect/timeline capabilities. The compact-tile format decision should not block Phase 1/2/3 from shipping.

5. Cross-reference: the closed epic Distant Horizons-style LOD overhaul: persistent chunk-derived hierarchical LOD #752 ("Distant Horizons-style LOD overhaul") and its Phase 5 LOD Phase 5: renderer batching & polish (vertex pooling, MDI, GPU culling, transitions) #757 already established the vertex-pool + MDI foundations that this epic now generalizes. Worth linking from each phase issue so reviewers can see what is genuinely net-new versus what was inherited and is merely being re-tuned. Also worth a brief note in LOD GPU roadmap Phase 0: establish profiling and quality baselines #921 about whether the Phase 0 instrumentation should be added to lod_bench_main.zig exclusively or also exposed via the headless benchmark skill for CI gating.

No missing info — the issue is self-contained and the phased delivery checklist matches the architectural assessment. Recommend opening the Phase 0 PR as the first deliverable.

[github-actions]

Comment posted on issue #923: #923 (comment)

Summary of classification and analysis:

• Classification: Feature Request (Epic / architectural roadmap)
• Scope: Already correctly decomposed into 6 phase sub-issues (LOD GPU roadmap Phase 4: compact GPU-rendered far-terrain tiles #917–LOD GPU roadmap Phase 5: quality, scale, and production hardening #922); no further splitting needed
• Key findings: Pointed to existing LODStats in modules/world-lod/src/lod_stats.zig as a natural Phase 0 extension point, called out Phase 1 as the cheapest/highest-confidence win, noted that Phase 2's RHI lifetime contract must merge first as a stubbed interface so Phase 3 builds against the real retirement path, flagged Phase 4 as the only representation-changing phase that warrants research-grade gating, and cross-referenced the closed predecessor epic Distant Horizons-style LOD overhaul: persistent chunk-derived hierarchical LOD #752 / phase LOD Phase 5: renderer batching & polish (vertex pooling, MDI, GPU culling, transitions) #757 for inherited vs. net-new work

opencode session  |  github run