Phase 5: persist generated LOD source data

[MichaelFisher1997]

Goal

Persist generated LOD source data so expensive representative terrain work can be reused across sessions.

Work Items

• Define cache keys using world seed, generator identity/version, LOD level, and region coordinates.
• Store source LOD data on disk, not GPU meshes.
• Add cache versioning and invalidation for data-format changes.
• Add bounded cache loading and save paths that do not block the render thread.
• Add corruption handling and safe regeneration fallback.

Acceptance Criteria

• Previously generated LOD source data can be loaded after restarting the game.
• Cache misses regenerate normally.
• Cache format changes invalidate or migrate safely.
• Render-thread stalls are avoided.
• zig build test passes.

[github-actions]

This is a well-scoped feature request for LOD cache persistence. A few observations to make the implementation tractable:

Dependency to address first: The GeneratorInfo struct currently has no version field—only a name string. The cache key requirements ("generator identity/version") cannot be fully met without adding versioning to generators. This should be the first sub-issue, likely as a separate PR.

Suggested sub-issues to break this down:

1. Add generator versioning — extend GeneratorInfo with a version: u32 field; each generator reports its current format version. This unlocks cache invalidation.

2. Define LOD cache file format — follow the existing pattern in chunk_serializer.zig (magic bytes + version byte + CRC32). Suggested path: saves/{world_name}/lod_cache/lod_{seed}_{gen_version}_{rx}_{rz}_{lod}.dat. The LODSimplifiedData struct would serialize heightmap, biomes, top_blocks, colors, material_layers, water, lighting, and vegetation as the cacheable "source data" (not GPU mesh).

3. Bounded async save path — leverage the existing LODManager worker pool. When a LODChunk reaches mesh_ready state and pin_count == 0, enqueue a background save. Do not block the render thread. The existing SaveManager pattern (queue + background thread + mutex) is a good reference.

4. Bounded async load path — on world open or when a region is first needed, check the cache before triggering generation. On cache miss, generate normally. Preloading can be staged by distance from spawn.

5. Corruption handling — validate on load (version check, CRC, struct bounds). On corruption, delete the bad cache file and regenerate.

Existing patterns to reuse:

• chunk_serializer.zig:CHUNK_DATA_VERSION / magic byte pattern
• SaveManager background threading model
• LODRegionKey for the spatial portion of the cache key

Note: The LodCacheKey should include seed, generator_version, and LODRegionKey ({rx, rz, lod}). Currently LODRegionKey only covers spatial+LOD level.

Would you like me to proceed with sub-issue 1 (generator versioning) as a first step?

opencode session  |  github run