Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Tool reference

Every tool is a module in src/zbtools/ exposing a Typer app, registered in pyproject.toml under [project.scripts] and run as uv run <name>. Defaults for inputs and outputs come from src/zbtools/paths.py; any can be overridden with arguments. The only code that knows about the host OS is host.py (binary locations, install hints, QEMU display and audio backends).

CommandModulePurpose
extract-gameextract_game.pydisc contents to build/disc/, the Windows 95 build to build/zoombi32/
unpack-iszunpack_isz.pylist/extract InstallShield 3 archives (hand-written: includes a DCL decompressor no Python library offers)
vmvm.pythe Windows 98 VM: install, install-game, run, reset, screenshot (the VM)
toolchaintoolchain.pyBorland C++ under Wine: setup, check, run
ghidraghidra.pysetup, open, decompile, label, codec (Ghidra notes)
runtime-symbolsruntime_symbols.pyname Borland runtime code by matching the toolchain's libraries (runtime and RTTI)
classesrtti.pyrecover C++ classes from RTTI into build/symbols/classes.json
matchmatch.pycompile and compare marked functions (Matching)
match-datamatch_data.pydata placement and data references (Data layout)
define-datadefine_data.pydefine declared-but-undefined globals with the original's initial values
near-missesnear_misses.pyclassify functions that don't match (Near-misses)
worklistworklist.pywhat's ready to decompile next
reportreport.pyHTML progress report in build/report/ (Jinja2 templates in src/zbtools/templates/). Contains disassembly: never publish.
modulesmodules.pythe module map and its evidence (Modules)
includesincludes.pyset each source's module-header includes
assetsassets.pyextract, pack, verify, frames (Formats)
movie-checkqb32.pyrun the original movie codec under emulation and compare every frame with ours
buildbuild.pycompile decomp/ and glue/ and link build/rebuild/zoombi32.exe (Rebuilt executable)
tracetrace.pyname the functions in a QEMU execution trace from the map
portport.pysetup, build, package, serve, run (The port)
bookbook.pybuild, serve and audit this book
cleanclean.pydelete generated files by category
lintlint.pyruff, ruff format, mypy, pytest

Supporting modules

ModuleRole
omf.pyminimal OMF object reader (Borland .OBJ), including "virtual segments" for type descriptors and templates
exe.pytyped pefile/capstone wrappers
demangle.pyBorland C++ demangler (demangle, qualified_name), checked against Borland's TDUMP on all 2,227 mangled names in CW32.LIB
declarations.pyreads the headers' structs, globals and prototypes (for Ghidra and define-data)
inventory.pyevery function with region, calls, module and status; backs worklist and report
module_map.pyloads decomp/modules.toml
quicktime.pythe QuickTime glue's stubs and selectors
mohawk.py, formats/, movies.pythe archive container, per-type formats and movie conversion
x86.pytyped wrapper for Unicorn (x86 emulation)
screen.pyrecognisers for Windows screens in the VM (logon prompt, idle desktop)
game_install.pybuilds the "tools CD" that vm install-game runs inside the VM
download.pythe shared pinned, checksum-verified download helper (Wine, Ghidra, Emscripten, SoundFont)
env.py, paths.py.env and every path the tools use, including CLEAN_CATEGORIES

Cleaning

Every path a tool generates must belong to a paths.CLEAN_CATEGORIES entry (categories may include others by name); add new ones there, and to CLEAN_DEFAULT if cheap to rebuild, and keep the cleaning table (docs/src/reference/cleaning.md) in sync.

Where the work is cached

CacheKeyed on
build/match-cache/source, local headers, options, release
build/assets-cache/the encoder's own output for compressed images (never the disc's bytes, or verify would test nothing)
build/ghidra/functions.jsonthe Ghidra project's analysis