LOD GPU roadmap Phase 4: compact GPU-rendered far-terrain tiles

[MichaelFisher1997]

Goal

Replace conventional CPU-expanded LOD3/4 meshes with compact height/material tiles and a GPU-friendly reusable representation. This is the main architectural step toward Distant Horizons-like scale.

Depends on

Phases 0-3. Requires measured evidence that CPU meshing, uploads, vertex memory, or vertex/raster work remains a limiting factor after earlier fixes.

Design spike

Before production implementation, compare:

1. Reusable indexed grid + compact tile textures/storage buffers.
2. Compute expansion into pooled vertex/index buffers.
3. Mesh shaders only on supported hardware with a conventional fallback.

Evaluate transfer bytes, VRAM, shader bandwidth, seams, normals, edit latency, platform support, and maintenance cost. Do not assume compute expansion is automatically superior.

Parallel workstreams after design approval

• Define compact quantized height, material, water, lighting, vegetation, and provenance representation.
• Implement CPU generation/persistence of compact tiles; avoid GPU readback.
• Implement reusable-grid or compute-generated rendering for LOD3/4.
• Generate normals from neighboring height samples with stable boundary handling.
• Implement skirts/stitching/geomorphing for cross-LOD seams.
• Add a simplified far-water pipeline without unnecessary SSR/reflection/depth work.
• Preserve CPU-mesh fallback and near LOD quality path.

Relevant code

• modules/world-core/src/lod_data.zig
• modules/world-lod/src/lod_mesh.zig
• modules/world-lod/src/lod_geometry.zig
• modules/world-lod/src/lod_seam.zig
• modules/world-lod/src/lod_vertex_pool.zig
• assets/shaders/vulkan/terrain.vert
• assets/shaders/vulkan/terrain.frag
• assets/shaders/vulkan/water.frag

CPU/GPU decision

CPU keeps procedural generation, edits, persistence, hierarchy policy, and compact-tile production. GPU handles expansion/rendering, normals where local, visibility, and drawing.

Acceptance criteria

• LOD3/4 upload bytes and resident geometry memory are materially lower than CPU-expanded meshes.
• Worker mesh time for far levels is eliminated or substantially reduced.
• Visual baselines show no unacceptable cracks, normal discontinuities, water artifacts, or transition instability.
• Quality can scale independently from raw vertex uploads.
• Unsupported devices use a maintained fallback.

Risks

Quantization artifacts, shader bandwidth replacing vertex bandwidth, difficult seams, edit propagation latency, and increased pipeline complexity. A design review is required before committing to mesh shaders.

[github-actions]

I have enough context. This is issue #917 in a roadmap series (Phases 0–5, all open). I will post an analysis comment only — no code changes.

---

Issue #917 — Analysis Comment

Classification: Feature Request (umbrella roadmap issue for LOD GPU work, Phase 4 of 6 — Phase 0 #921, Phase 1 #920, Phase 2 #919, Phase 3 #918, Phase 4 #917, Phase 5 #922).

Validation & gating dependencies

The issue itself is well-structured as a roadmap document, but a few things should land before any production sub-issue is opened:

1. Profiling evidence — the body says Phase 4 "requires measured evidence" that CPU meshing / uploads / vertex memory / vertex‑raster work remains the bottleneck after Phases 0–3 land. That evidence should be a published artifact (numbers, capture, or issue link) so we don't ship Phase 4 optimistically.
2. Design spike deliverable — the three candidate approaches (reusable indexed grid + compact tile textures/SSBOs, compute expansion into pooled vertex/index buffers, mesh shaders with fallback) are correctly framed as a comparison, not a foregone conclusion. I'd like the spike to land as a written decision record (small ADR in docs/ or a design/ note) covering transfer bytes, VRAM, shader bandwidth, seams, normals, edit latency, platform support, and maintenance — the seven criteria the author already listed. No implementation work should start before that decision is recorded.
3. Fallback contract — the "Preserve CPU‑mesh fallback and near LOD quality path" bullet needs to be turned into an explicit acceptance test/gate so Phase 5 hardening can't regress to a mesh‑shader‑only build.

Scope — please split into sub-issues

This umbrella is genuinely too large for a single PR and crosses too many subsystems (world-core data layout, world-lod mesh + seam + vertex pool, world-meshing, assets/shaders, water pipeline, persistence). The workstream checklist in the body is already the right decomposition — I'd convert each unchecked box into a tracked sub-issue with the relevant code pointers, then close this umbrella as a tracking meta-issue that links them.

Suggested sub-issue split (one issue per box, each scoped to merge independently):

• Sub‑A — Compact tile representation (depends on spike outcome)
  • Quantized height / material / water / lighting / vegetation / provenance formats.
  • Owner files: modules/world-core/src/lod_data.zig, additions to modules/world-core/src/block.zig & block_registry.zig if material IDs change.
• Sub‑B — CPU tile generation + persistence (no GPU readback; plays nicely with world-persistence save manager).
  • Hooks into lod_generator.zig / lod_ingest.zig; new tile writer in world-persistence.
• Sub‑C — Reusable‑grid or compute expansion renderer for LOD3/4 (winner of spike).
  • Touches modules/world-lod/src/lod_mesh.zig, lod_geometry.zig, lod_vertex_pool.zig, and the new pipeline likely needs an RHI vtable addition rather than touching lod_renderer.zig directly (per the RHI‑seam rules from the audit umbrella).
• Sub‑D — Normal generation from neighboring samples with stable boundaries
  • Shared logic; must agree with lod_seam.zig so cross‑LOD normals don't pop.
• Sub‑E — Skirts / stitching / geomorphing across LOD seams
  • Pure lod_seam.zig work; needs visual baselines from the headless‑screenshot skill before/after.
• Sub‑F — Simplified far‑water pipeline
  • New shader path; assets/shaders/vulkan/water.frag and possibly a water_lod.frag variant. Must keep the SSR/reflection/depth work gated to near water only.
• Sub‑G — CPU‑mesh fallback + near LOD quality preservation
  • Feature‑flag the new path so Phase 5 can ship progressive rollout; needs a regression‑test scenario for the headless‑screenshot skill.

A sensible ordering: spike → A → B → D → C → E → F → G, because D's normal rules need to exist before C stitches them, and G is the safety net that should be wired in alongside C, not after.

Cross‑subsystem risk notes

• lod_manager.zig was just decomposed (issue [R2-1][P1] Decompose LODManager God-object (2,715 LOC → ~500) #840). Phase 4 should plug into lod_manager_*_ops.zig modules rather than re‑introducing a god‑object pattern — flagging now so sub‑issues don't drift back toward the anti‑pattern.
• lod_vertex_pool.zig and lod_mesh_resources.zig already exist; the reusable‑grid approach can largely live there, but the compute‑expansion approach likely needs a new lod_compute_expand.zig module to keep RHI calls off worker threads (per AGENTS.md job‑system rules).
• Water LOD has to agree with the in‑flight Lighting Overhaul umbrella ([Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898) — worth a heads‑up in that issue when Sub‑F starts.

Requested from the author / reviewer

• Confirm the design spike will produce a written decision record (link to expected path) before any sub‑issue is opened.
• Confirm Phases 0–3 profiling will be linked into this issue as evidence.
• Once the split is agreed, I'll open the seven sub-issues as children of LOD GPU roadmap Phase 4: compact GPU-rendered far-terrain tiles #917 and convert this issue into a tracking meta-issue with a checklist linking them. No implementation until the spike lands.

Happy to draft the sub-issue bodies once the spike decision and profiling evidence are linked.

opencode session  |  github run