-
Notifications
You must be signed in to change notification settings - Fork 0
CLI Tool
Void includes a command-line tool for creating, updating, and managing asset packs. The tool is used during development, not by players.
Install the CLI tool as a .NET global tool:
dotnet tool install --global Void.Packer.CLI
Or run it from the source:
dotnet run --project Void.Packer.CLI -- build -c Content/ -o Packs/
All commands that read packs (extract, verify, list, update) automatically detect the key file. If you have GameAssets.pack, the tool looks for GameAssets.key in the same directory. You only need to specify --key if the key is in a different location.
All commands show user-friendly error messages instead of raw exceptions:
❌ Error: Invalid encryption key.
❌ Error: Pack was created with a newer version.
❌ Error: Pack file not found.
This makes the CLI tool approachable for non-programmers (artists, level designers) who might run pack commands.
All commands return 0 on success and 1 on failure. This makes them suitable for CI/CD pipelines and build scripts.
These options are available on all commands:
| Option | Short | Description | Default |
|---|---|---|---|
| --verbose | -v | Verbose output with detailed error information | false |
| --no-wait | Don't wait for key press after completion | false | |
| --no-color | Disable colored output | false |
The update operation is fast because it only processes files that have changed. It reads the header to understand the pack structure, streams the existing data to the new pack without loading it into memory, and only rewrites the parts that need to change. For a 2GB pack with one changed file, the update takes seconds instead of the 10-20 minutes it would take to rebuild the entire pack.
Creates a new pack from your content directory.
void-packer build -c Content/ -o Packs/ -n GameAssets
The build command shows live progress with current file, completion count, and time remaining for large operations.
Options
| Option | Short | Description | Default |
|---|---|---|---|
| --content | -c | Content directory to pack | Required |
| --output | -o | Output directory for .pack and .key files | Required |
| --name | -n | Base name for output files | GameAssets |
| --include | -i | Include patterns (comma separated) | */ |
| --exclude | -e | Exclude patterns (comma separated) | None |
| --encrypt | Enable encryption | true | |
| --compress | Compression algorithm: None, Deflate, Brotli | Deflate | |
| --adaptive | Use adaptive compression | true | |
| --compression-level | Compression level (1-9) | 6 | |
| --max-files | Maximum files per pack | 65535 | |
| --chunk-size | Chunk size in KB for chunked encryption (0 = solid) | 1024 | |
| --case-sensitive | Case sensitive virtual paths | false |
Include Patterns Include patterns use glob matching:
| Pattern | What it matches |
|---|---|
| */ | All files in all folders |
| **/*.png | All PNG files in all folders |
| textures/* | All files in the textures folder (not subfolders) |
| */player. | Any file named "player" with any extension |
| data/*.json | JSON files in the data folder |
Exclude Patterns Exclude patterns work the same way but remove files from the include list:
void-packer build -c Content/ -o Packs/ -e "**/*.ase*, **/Fonts/FontDialog.png"
Chunk Size Chunk size controls how the data section is encrypted:
| Value | Behavior |
|---|---|
| 0 | Solid encryption (entire data section as one blob) |
| 1024 (default) | 1MB chunks - only needed chunks decrypted on read |
| 2048 | 2MB chunks - fewer chunks, more decrypted per read |
| 512 | 512KB chunks - more chunks, less decrypted per read |
Small packs (smaller than the chunk size) automatically use solid encryption regardless of this setting.
Updates an existing pack by adding or removing files. Fast incremental updates take seconds, not minutes.
void-packer update --pack GameAssets.pack --add Content/newfile.png --remove old/texture.png
Options
| Option | Short | Description | Default |
|---|---|---|---|
| --pack | Existing pack file to update | Required | |
| --add | -a | Files or folders to add | None |
| --remove | -r | Virtual paths of files to remove | None |
| --key | Key file (required if encrypted) | Auto-detected | |
| --output | -o | Output path for updated pack | Overwrite |
The key is auto-detected if a .key file exists with the same name as the pack.
Extracts all files from a pack.
void-packer extract --pack GameAssets.pack --output Extracted/
The extract command shows live progress with current file, completion count, and total size extracted.
Options
| Option | Short | Description | Default |
|---|---|---|---|
| --pack | Pack file to extract | Required | |
| --output | -o | Output directory | Required |
| --key | Key file (required if encrypted) | Auto-detected |
The key is auto-detected if a .key file exists with the same name as the pack.
Verifies the integrity of a pack by checking CRC32 checksums for every file.
void-packer verify --pack GameAssets.pack
Options
| Option | Short | Description | Default |
|---|---|---|---|
| --pack | Pack file to verify | Required | |
| --key | Key file (required if encrypted) | Auto-detected |
Verification reads the header, decrypts it, then for each file, reads the data, calculates its CRC32 checksum, and compares it to the stored checksum. Any mismatch is reported.
Lists all files in a pack.
void-packer list --pack GameAssets.pack --detailed
Options
| Option | Short | Description | Default |
|---|---|---|---|
| --pack | Pack file to inspect | Required | |
| --key | Key file (required if encrypted) | Auto-detected | |
| --detailed | Show detailed info (size, compression, CRC) | false |
Detailed output shows the virtual path, uncompressed size, compressed size, compression status, and CRC32 checksum for each file.