[Batch 1] Region file format: read/write with zlib compression

[MichaelFisher1997]

Summary

Implement a .mca-style region file format for chunk storage. Each region file holds a 32×32 grid of chunks with a location table and compressed chunk payloads. This is the foundation for world persistence — no world save/load exists currently.

Current State

The world is entirely ephemeral:

• Chunks are generated procedurally via worldgen and held in a ChunkStorage HashMap
• When the player quits, all changes are lost
• There is no file I/O for chunk data anywhere in the codebase
• ECSRegistry.saveToJson()/loadFromJson() exist but are never called for world state

Specification

Region File Layout

[Header: 1024 bytes]
  - 1024 entries × 4 bytes each (256 rows × 4 columns = 1024 chunk slots)
  - Each entry: 3 bytes offset (in 4KiB sectors) + 1 byte sector count
  - Offset 0 = chunk not present

[Chunk Data: variable length]
  - Each chunk: 4-byte length + 1-byte compression type + compressed payload
  - Compression: zlib (standard deflate)
  - Sectors are 4096 bytes, chunks may span multiple sectors

This matches the Minecraft Anvil .mca format closely, which is well-understood and efficient.

API

const RegionFile = struct {
    pub fn open(path: []const u8) !RegionFile;
    pub fn create(path: []const u8) !RegionFile;
    pub fn close(self: *RegionFile) void;

    pub fn hasChunk(self: *RegionFile, local_x: u5, local_z: u5) bool;
    pub fn readChunk(self: *RegionFile, local_x: u5, local_z: u5, allocator: Allocator) ![]u8;
    pub fn writeChunk(self: *RegionFile, local_x: u5, local_z: u5, data: []const u8) !void;
    pub fn deleteChunk(self: *RegionFile, local_x: u5, local_z: u5) void;
};

Region Coordination

• World chunk (cx, cz) → region file r.{cx/32}.{cz/32}.mca → local slot (cx%32, cz%32)
• Region directory: ~/.config/zigcraft/saves/<world-name>/regions/

Implementation Plan

1. Create src/world/persistence/region_file.zig

   • File open/create with header read/write
   • Location table parsing (little-endian)
   • Chunk read: seek to offset, read length+compression, decompress
   • Chunk write: compress, find free sectors or append, update header
   • Chunk delete: zero out header entry, mark sectors free

2. Unit tests

   • Round-trip: write chunk → close → reopen → read chunk → verify identical
   • Multiple chunks in one region
   • Overwrite existing chunk (old data freed, new data appended)
   • Empty region (no chunks written)
   • Corrupt header handling (graceful error, not crash)

3. Free sector tracking

   • Simple approach: scan header on open to build free list
   • New chunks appended at end of file
   • Freed sectors tracked for reuse (optional optimization for later)

Dependencies

• zlib — available via system libraries (Nix flake may need zlib added)
• Alternative: use std.compress.zlib from Zig stdlib if sufficient

Files to Create

• src/world/persistence/region_file.zig — core implementation
• src/world/persistence/zig — module root (if using directory module)

Testing

• Round-trip chunk data integrity
• Multiple chunks per region
• Chunk overwrite replaces data correctly
• File corruption handled gracefully
• Empty regions create valid files

Roadmap: docs/PERFORMANCE_ROADMAP.md — Batch 1, Issue 1B-1

[opencode-agent]

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

Classification: Feature Request

Analysis:

This is a well-structured feature request for implementing Minecraft Anvil-style region file persistence. The specification is thorough and the scope is appropriately bounded to the region file I/O layer.

Key Findings:

1. Current state confirmed - World is ephemeral with chunks stored in ChunkStorage HashMap (src/world/chunk_storage.zig:67). No persistence exists.

2. zlib dependency gap - flake.nix currently lacks zlib. You'll need to add pkgs.zlib to buildInputs and link it in build.zig to use system zlib. Alternatively, std.compress.zlib from Zig stdlib is available but limited to decompression only— you'd need a pure-Zig deflate implementation for compression.

3. Missing roadmap file - Issue references docs/PERFORMANCE_ROADMAP.md which doesn't exist in the repo.

4. Serialization format undefined - The region file spec is clear, but the actual chunk payload format (what bytes get compressed) needs definition. Consider:

   • Block data: 65,536 bytes (BlockType u8 array)
   • Light data: 131,072 bytes (PackedLight u16 array)
   • Biomes: 256 bytes
   • Heightmap: 512 bytes
   • Total uncompressed: ~196KB per chunk → ~25KB compressed (typical 8:1 ratio)

Suggested Approach:

This is appropriately scoped as a single feature. The implementation should:

• Focus purely on the region file container (headers, sector management, compression wrapper)
• Accept/return raw byte slices for chunk data (leave serialization to a follow-up)
• Include comprehensive unit tests for corruption handling

No critical info is missing—this is ready for implementation once the zlib approach is decided.

opencode session  |  github run