LOD GPU roadmap Phase 5: quality, scale, and production hardening

[MichaelFisher1997]

Goal

Turn the optimized architecture into a stable, high-quality distant-terrain system at large horizons.

Depends on

Phases 0-4. Individual quality tasks may start earlier when they do not conflict with the far-tile representation.

Parallel workstreams

Visual quality

• Make parent/child refinement temporally stable under movement and streaming delays.
• Integrate crack-free seams, skirts, or geomorphing across all active LOD boundaries.
• Improve material/biome aggregation, lighting hints, normals, vegetation silhouettes, fog, and far-water handoff.
• Remove fragment-discard masking where coarse geometry can be clipped/cut earlier without holes.
• Verify edited/chunk-derived provenance survives generator/cache transitions.

Streaming and persistence

• Improve predictive traversal scheduling and cancellation without starving nearby detail.
• Validate cache format/versioning, asynchronous compaction, corruption recovery, and bounded writeback.
• Fix pause/unpause and stale-job state reconciliation.
• Stress test large horizons, rapid teleport, edits, save/reload, low-memory pressure, and long sessions.

Production gates

• Define quality presets that scale sample density, horizon, water, vegetation, culling, and memory coherently.
• Establish CPU/GPU/memory budgets and regression thresholds per preset.
• Add visual and performance regression coverage for representative hardware tiers.
• Document feature requirements and fallback behavior.

Relevant code

• modules/world-lod/
• modules/world-runtime/src/world_streamer.zig
• modules/world-runtime/src/world_renderer.zig
• modules/worldgen-overworld-v2/src/lod_sampling.zig
• assets/shaders/vulkan/terrain.*
• assets/shaders/vulkan/water.*

Acceptance criteria

• Large-radius traversal meets agreed p95/p99 CPU and GPU frame budgets without unbounded memory growth.
• No visible hierarchy holes, persistent cracks, severe popping, or incorrect full-detail handoff in automated captures.
• Save/reload and edit propagation are deterministic and corruption-tolerant.
• Presets have documented VRAM/RAM/performance targets and degrade gracefully.
• Long-running robustness tests report no GPU validation errors, stale resources, deadlocks, or permanently stuck LOD states.

Architectural outcome

Success means a hybrid system: CPU-driven generation, persistence, edits, and policy; GPU-driven far representation, visibility, and submission. Matching Distant Horizons-like scale is realistic only after compact far tiles and hierarchical GPU-driven rendering are proven.

[github-actions]

Thanks for the detailed Phase 5 roadmap — acceptance criteria and the explicit "Depends on Phases 0-4" gate make this very actionable. A few observations from a review pass:

Classification: Feature Request (epic / umbrella).

Code paths verified: All referenced files exist and align with the workstreams:

• modules/world-lod/ covers hierarchy/scheduling/eviction.
• modules/world-runtime/src/world_streamer.zig and world_renderer.zig cover the streaming + submission side.
• modules/worldgen-overworld-v2/src/lod_sampling.zig owns biome/aggregation provenance.
• assets/shaders/vulkan/terrain.* and water.* cover the visible-quality workstream.

Prior art: Phase 5 was already used for #757 ("renderer batching & polish"), which has shipped. This issue is correctly positioned as the post-optimization hardening pass — not a duplicate.

Scope: please break this into sub-issues. Three workstreams × 4–5 unchecked items each is too large to land as a single epic. Each checkbox is independently PR-able and will be much easier to review, gate, and roll back individually. Suggested split:

1. Visual quality (label: shaders, perf/rendering)

   • 5a. Temporal stability of parent/child refinement under movement + streaming delay.
   • 5b. Crack-free seams across LOD boundaries (skirts vs. geomorphing — pick one in the sub-issue body so it's not a moving target).
   • 5c. Material/biome aggregation + lighting hints, normals, vegetation silhouettes, fog, far-water handoff.
   • 5d. Remove fragment-discard masking where coarse geometry can be CPU-clipped earlier.
   • 5e. Provenance survival across generator/cache transitions.

2. Streaming & persistence (label: engine, world)

   • 5f. Predictive traversal scheduling + cancellation that doesn't starve nearby detail.
   • 5g. Cache format/versioning, async compaction, corruption recovery, bounded writeback.
   • 5h. Pause/unpause + stale-job reconciliation.
   • 5i. Stress harness for large horizons, teleport, edits, save/reload, low-mem, long sessions.

3. Production gates (label: documentation, perf/rendering)

   • 5j. Quality preset definitions (density/horizon/water/veg/culling/memory) — needs explicit per-preset numbers to be reviewable.
   • 5k. CPU/GPU/memory budgets + regression thresholds per preset.
   • 5l. Visual + perf regression coverage on representative hardware tiers (CI matrix).
   • 5m. Documentation of feature requirements + fallback behavior.

Suggestions to land the umbrella cleanly:

• Keep LOD GPU roadmap Phase 5: quality, scale, and production hardening #922 as the tracking epic; reference each sub-issue from its checkbox via Refs #NNN so closing all of them auto-flips this one.
• Pin the budget numbers (p95/p99, VRAM/RAM caps, max horizon radius per preset) up front in the first sub-issue — without them, "production gates" tasks can't be marked done.
• The architectural outcome sentence ("hybrid CPU/GPU, Distant Horizons-like scale only after compact far tiles + hierarchical GPU rendering") is a great north star; recommend copying it into each sub-issue body so contributors don't lose the framing.

No blockers — just want to make sure this doesn't become a graveyard issue. Happy to draft the first sub-issue (5a or 5j) if useful.

[github-actions]

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

Summary of analysis:

• Classification: Feature Request (epic/umbrella)
• Validation: Issue is well-formed; acceptance criteria are concrete; all referenced code paths (modules/world-lod/, world_streamer.zig, world_renderer.zig, lod_sampling.zig, terrain.*/water.* shaders) verified to exist
• Prior art check: A prior "Phase 5" (LOD Phase 5: renderer batching & polish (vertex pooling, MDI, GPU culling, transitions) #757) already shipped (renderer batching & polish); this issue is correctly the post-optimization hardening iteration, not a duplicate
• Scope recommendation: Strongly recommended breaking the three workstreams × 4–5 items into ~13 individually-PR-able sub-issues with explicit per-preset budget numbers, keeping LOD GPU roadmap Phase 5: quality, scale, and production hardening #922 as the tracking epic
• Labels: Existing labels (engine, world, shaders, perf/rendering, documentation) map cleanly onto the proposed sub-issue grouping

opencode session  |  github run