Quickstart

This walks the whole tool in one sitting. Point it at any directory you have lying around; the numbers below come from a 56-file asset tree.

1. Pack a directory

   $ zpack pack assets/ game.zpak
   Packed 56 files (77.2 MiB -> 71.7 MiB, 7.1% smaller)

   Every file under assets/ is walked recursively. Each one is deflated, and kept compressed only if that came out smaller - which is why an asset tree that is mostly PNGs and Ogg files barely shrinks. Nothing grows.

2. See what is in it

   $ zpack list game.zpak
   audio/void_mp_emh_1.wav                    35.2 MiB  deflate    32.4 MiB
   textures/asphalt_old_pt_1.png             153.2 KiB  store     153.2 KiB
   textures/ui/label.txt                           6 B  store           6 B

   Columns are path, original size, method, and stored size. The index lives at the head of the file, so this reads a few kilobytes rather than the whole archive - list on a 70 MiB archive costs the same as on a 70 KiB one.

3. Check it is intact

   $ zpack verify game.zpak
   Verified 56 entries

   This one does read everything: each entry is decompressed and rehashed against the hash recorded when it was packed. It writes nothing to disk.

4. Extract it

   $ zpack unpack game.zpak extracted/
   Extracted 56 files

   Parent directories are created as needed. Contents are hashed as they stream, so a corrupt entry fails during extraction rather than silently producing a bad file.

5. Confirm the round trip

   $ diff -r assets/ extracted/

   No output. The trees are identical.

Repacking is reproducible

Entries are sorted by path before writing, so the same tree always produces the same bytes:

$ zpack pack assets/ a.zpak
$ zpack pack assets/ b.zpak
$ cmp a.zpak b.zpak      # no output: identical

That holds across machines and platforms too - paths are normalized to / regardless of the host separator.

Packing into the directory being packed

zpack pack . out.zpak skips a file whose relative path equals the output path, so running it twice does not fold the previous archive into the new one. The temporary file it builds into is created after the scan, so it never appears in its own archive either.

Leaving files out

Drop a .zpackignore at the root of the directory you are packing:

assets/.zpackignore

# art sources, not shipped
*.psd
*.blend

# os junk, at any depth
.DS_Store
Thumbs.db

The syntax is a subset of .gitignore. The ignore file itself never ends up in the archive. See .zpackignore for the full pattern rules.

Next

• Give your game compile-checked asset handles with zpack ids
• Read from an archive in Zig instead of shelling out - library overview
• Wire packing into build.zig so assets rebuild with the project - build integration