ids

zpack ids <archive.zpak>

Writes a Zig source file to stdout containing one enum constant per entry:

$ zpack ids game.zpak > src/assets.zig

src/assets.zig

// Generated by zpack from game.zpak. Do not edit.

pub const Asset = enum(u64) {
    @"audio/blip.wav" = 0x40a8e93753577eb5,
    @"data/noise.bin" = 0xbc5d025c01217e9b,
    @"jimmy.png" = 0xda77d2ecbff2fabb,
    @"levels/level-01.json" = 0x3a43adffebb476d2,
    @"shaders/sprite.frag" = 0xc51bb341f35636a4,
};

Paths become quoted identifiers, so they survive /, ., and - unchanged. The header names the archive the enum came from.

Using the handles

const Asset = @import("assets.zig").Asset;

const entry = archive.findId(@intFromEnum(Asset.@"textures/player.png")).?;

Rename an asset without regenerating and the build fails at the enum reference, rather than returning null at load time on a player’s machine. That is the whole point of the command - see asset handles for the full workflow.

The handles are stable

A handle is XxHash64 of the path under a fixed seed. The same path always yields the same id, so:

• A handle survives a repack. Regenerating after adding assets does not disturb the existing ones.
• Nothing about the handle is stored in the archive. It is derived, not recorded.
• Anywhere can compute one: zpack.format.assetId("textures/player.png") gives the identical u64.

Collisions are a build error

Two different paths hashing to the same u64 would make one asset unreachable. Rather than tolerate that, both pack and Archive.open reject it:

$ zpack pack assets/ game.zpak
zpack: cannot pack 'assets/': AssetIdCollision

So a collision surfaces at build time, on the change that introduced it, instead of serving the wrong asset at runtime. With 64 bits, reaching a coin-flip chance of one collision takes around five billion paths.

Cost

Only the index is read. ids never touches the data region, so it is as cheap as list.

Redirecting safely

Output goes to stdout; errors go to stderr. A failing ids leaves an empty target file rather than half an enum with an error message appended.

To generate the file as part of a build instead of by hand, see build integration.