Embedded world storage built for fast chunk saves and reads.

ZigriteDB is an embedded storage engine for Minecraft Bedrock worlds, written in Zig and built for Quark. Append-only writes, batched saves, indexed reads, and LZ4 compression keep storage focused on individual chunk components.

In development. The API and file format may change. Not yet recommended for production worlds.

Build

Requires Zig 0.16.0 and Linux for storage operations.

zig build -Doptimize=ReleaseSafe

Zig API

Place a checkout at vendor/zigritedb and add this to your application's build.zig, using its existing exe, target, and optimize:

exe.root_module.addImport("zigritedb", b.createModule(.{
    .root_source_file = b.path("vendor/zigritedb/src/root.zig"),
    .target = target,
    .optimize = optimize,
}));

Create a world directory, then save and read a component:

const std = @import("std");
const db = @import("zigritedb");

pub fn main() !void {
    const allocator = std.heap.page_allocator;
    var threaded = std.Io.Threaded.init(allocator, .{});
    defer threaded.deinit();
    const io = threaded.io();

    const dir = try std.Io.Dir.cwd().openDir(io, "world", .{});
    defer dir.close(io);
    var world = try db.World.open(allocator, io, dir, .{});
    defer world.deinit();

    const key: db.Key = .{
        .dimension = 0,
        .chunk_x = 4,
        .chunk_z = 8,
        .component = .metadata,
    };
    const last_id = (try world.lastBatchId(key.region())) orelse 0;
    const data = "chunk data";
    _ = try world.write(.{ .entries = &.{.{
        .key = key,
        .header = .{
            .kind = .put,
            .batch_id = try std.math.add(u64, last_id, 1),
            .stored_len = data.len,
            .raw_len = data.len,
        },
        .value = data,
    }} });

    var buffer: [64]u8 = undefined;
    const saved = (try world.get(key, &buffer)) orelse return error.NotFound;
    std.debug.print("{s}\n", .{saved});
    try world.close();
}

Batches are atomic within one 32×32 chunk region and use increasing IDs. Writes sync by default; buffered writes require a successful flush for durability. Call close to flush and report errors; deinit only releases resources. See World for the full Zig API.

For other languages, link against libzigritedb_native and use zigritedb.h. Libraries and headers are installed under zig-out/lib and zig-out/include.

Benchmarks

zig build bench -Doptimize=ReleaseSafe
python3 tests/bench/run.py --directory /path/to/benchmark/filesystem

Outputs synthetic latency, memory, and storage measurements as JSON. Compare equivalent workloads and durability settings.

Testing

zig build test
zig build test -Doptimize=ReleaseSafe
zig build fuzz --fuzz=10000

Native fault and workload checks live in tests/native. See CI for the full verification commands.

License

See LICENSE.