Skip to content

Tools ​

ToolUse it for
Golden vectorsProving a port gives the TypeScript's results, bit for bit
Parser fuzzingProving the parsers of downloaded and network data never panic

SHAG's CLI, server and headless tools (SHAG Tools) stay in TypeScript. Run them from a SHAG checkout; the native client talks to the servers they start.

Parser fuzzing ​

crates/shagger/tests/fuzz_parsers.rs mutates real files (bit flips, boundary values, truncation, splices) and feeds them to every parser that reads bytes from a downloaded package or from the network. Each parser must return an error rather than panic, since a panic is a crash in the game. It runs on stable Rust with no extra tools, and is ignored by default.

FUZZ_DATA names a folder of .pk3 packages (the synced game data), whose files are the seeds:

sh
FUZZ_DATA=<dir> FUZZ_ITERS=2000 cargo test --release -p shagger \
    --test fuzz_parsers -- --ignored --nocapture
VariableMeaningDefault
FUZZ_DATAthe folder of seed packagesrequired
FUZZ_ITERSmutations per seed500
FUZZ_SEEDShow many seed files to sample per target (every model is always taken, and at most three maps)12
FUZZ_ONLYa comma-separated list of targets to runevery target
FUZZ_OUTwhere failing inputs are writtentarget/fuzz

Each failing input is written to FUZZ_OUT and reported by target and seed file. To replay one, set FUZZ_REPLAY to the file and FUZZ_TARGET to its target, and run the ignored fuzz_replay test.

Released under the MIT License. Babylon.js ports under Apache-2.0.