[Batch 5] Chunk block data GPU storage buffer

[MichaelFisher1997]

Summary

Upload chunk block data (1 byte per block) to a GPU storage buffer so that a compute meshing shader can read blocks directly. This is the foundation for GPU-driven mesh generation.

Depends on: #384 (transfer queue for uploading block data efficiently)

Current State

Block data lives only in CPU memory (Chunk.blocks: [16][256][16]BlockType). Meshing reads blocks on CPU worker threads, produces vertex arrays, uploads vertices to GPU. The GPU never sees raw block data.

Target State

A GPU-visible storage buffer holds block data for all loaded chunks. Layout:

Buffer: [chunk_0_blocks | chunk_1_blocks | ... | chunk_N_blocks]
Each chunk: 16 × 256 × 16 = 65536 bytes (BlockType is u8)
Total: 16384 chunks × 64KB = 1GB max

A compute meshing shader (future issue) can read blocks from this buffer and output vertices directly on the GPU — no CPU meshing, no vertex upload.

Implementation Plan

Step 1: Block data buffer management

const GpuBlockBuffer = struct {
    buffer: BufferHandle,
    capacity: usize,            // max chunks
    slot_size: usize,           // 65536 bytes per chunk
    allocator: FreeListAllocator,  // which slots are in use
    
    pub fn allocate(self: *GpuBlockBuffer, chunk_index: u32) !usize;
    pub fn free(self: *GpuBlockBuffer, slot: usize) void;
    pub fn upload(self: *GpuBlockBuffer, slot: usize, blocks: []const u8) !void;
};

Step 2: Chunk index mapping

• Need a mapping: chunk coordinate (cx, cz) → buffer slot index
• Could use the same index as ChunkStorage HashMap (iterate and assign)
• Or: sparse mapping with a lookup texture/buffer

Step 3: Upload integration

• When a chunk finishes generating: upload block data to GPU storage buffer
• Use the transfer queue ([Batch 4] Dedicated transfer queue + staging buffer ring #384) for upload
• Mark slot as allocated
• When chunk unloads: free the slot

Step 4: Lighting data (optional, same buffer or separate)

• sky_light and block_light could go in the same buffer (appended after blocks)
• Or a separate buffer for light data
• Keep it simple for this issue: blocks only, light stays on CPU for now

Step 5: Integration with chunk lifecycle

• WorldStreamer: after chunk generates, call gpu_block_buffer.upload()
• WorldStreamer: when chunk unloads, call gpu_block_buffer.free()
• Player modifies block: update both CPU chunk and GPU buffer (small sub-region upload)

Files to Create

• src/world/gpu_block_buffer.zig — GPU block data buffer management

Files to Modify

• src/world/world_renderer.zig — own and manage GpuBlockBuffer
• src/world/world_streamer.zig — upload block data on generate, free on unload
• src/game/player.zig — update GPU buffer on block break/place

Testing

• Block data uploads for all chunks within render distance
• Slots freed correctly on chunk unload
• Block modifications reflected in GPU buffer (verify by reading back)
• Memory bounded: doesn't exceed max allocation
• No performance regression from upload overhead
• Works with 0 chunks, 1 chunk, 16384 chunks

Roadmap: docs/PERFORMANCE_ROADMAP.md — Batch 5, Issue 4A-1

[opencode-agent]

Based on my analysis of the codebase, here's my assessment:

Classification

Feature Request - Well-structured implementation plan for GPU-driven mesh generation foundation.

Analysis

The infrastructure for this feature is already in place:

1. RHI Storage Buffer Support: BufferUsage.storage is defined (src/engine/graphics/rhi_types.zig:48) and implemented in the Vulkan backend with VK_BUFFER_USAGE_STORAGE_BUFFER_BIT (src/engine/graphics/vulkan/resource_manager.zig:300)

2. Transfer Queue Ready: Issue [Batch 4] Dedicated transfer queue + staging buffer ring #384 dependency is satisfied - transfer command buffers, fences, and upload pipeline are fully implemented (src/engine/graphics/vulkan/resource_manager.zig:105-108, prepareTransfer() at line 274)

3. Chunk Data Layout: Current Chunk.blocks: [CHUNK_VOLUME]BlockType provides exactly 65,536 bytes per chunk as specified (src/world/chunk.zig:114)

4. Upload Infrastructure: uploadBuffer()/updateBuffer() methods with staging buffers and transfer commands are ready (src/engine/graphics/vulkan/resource_manager.zig:325-363)

Architectural Considerations

Integration Points (all align with your plan):

• Hook into WorldStreamer.processGenJob() completion (line 426) for initial upload
• Free slots in chunk unload logic (around line 388)
• Block modifications via World.setBlock() (line 252-284) need GPU buffer updates

Implementation Suggestions:

1. Memory Barrier: When the compute shader reads the storage buffer, you'll need VK_ACCESS_SHADER_READ_BIT in the pipeline barrier. The current updateBuffer() includes this (line 355), but verify compute shader stage is covered.

2. Descriptor Set: Consider how the compute shader will access this buffer - you may need to extend descriptor management to bind the storage buffer to a compute pipeline.

3. Sub-region Updates: For block break/place, consider implementing a small update path (64 bytes for a single block vs 64KB full chunk reupload) to minimize transfer overhead.

Scope Assessment

This issue is appropriately scoped as a single unit. The 5 implementation steps are tightly coupled to one feature and should proceed together in one PR.

Testing Strategy: Your checklist covers the critical paths. Consider adding a debug visualization mode to verify GPU buffer contents match CPU state (helpful for development).

This is ready for implementation - the foundation is solid and the plan is comprehensive.

opencode session  |  github run