Guide Modkit

The modkit CLI

tools/modkit.py is the mod-author command line: scaffold, validate, lint, pack, bounce, docs. Python 3; the validate path also needs luajit on your PATH (override with MODKIT_LUAJIT).

python3 tools/modkit.py <subcommand> [args]

Global flags: --repo PATH (repo root override), --json, --quiet. Exit codes: 0 success, 1 validation/lint failure, 2 usage error.

scaffold

python3 tools/modkit.py scaffold my_mod
python3 tools/modkit.py scaffold my_tc --profile total_conversion

Creates mods/<id>/ with a manifest v2 (api: 2, the current engine's game_version range), a commented main.lua, a README.md, a .luarc.json, and an assets/ directory. The total_conversion profile adds a transforms.lua and wires assets_transforms. Flags: --profile content|overhaul|total_conversion, --dest DIR, --force.

validate

python3 tools/modkit.py validate my_mod [--strict] [--base auto|fixture|imported]

Drives the real engine loader headlessly, so a mod that passes will not surface load errors in-game: manifest shape (MK001–MK004), permission vocabulary (MK005) and undeclared engine requires (MK006), schema violations, dangling cross-references, and vanilla-id checks (MK1xx). --base auto folds over the player's imported dataset when one exists and falls back to the ROM-free fixture (tests/fixture_data/) otherwise — which is what keeps the tool runnable on a CI box with no ROM. Rules that need the real id space (MK103) are reported as skipped over the fixture, never guessed.

lint

python3 tools/modkit.py lint my_mod

The no-ROM-content distribution gate:

Rule	Refuses
MK301	files in (or pointing into) the generated trees
MK302	byte-identical or perceptually near-duplicate assets vs the player's cache
MK303	ROM images and ROM-hack patch formats (.gb, .gbc, .ips, .bps)
MK304	raw chip-audio banks (ROM-derived)

pack

python3 tools/modkit.py pack my_mod [-o out.modpkg]

Runs validate and lint at strict level — any finding, warning included, refuses the package — then zips the mod for distribution. See Publishing.

bounce

python3 tools/modkit.py bounce Music_ModChip --seconds 30
python3 tools/modkit.py bounce --all --out renders/

Renders chip songs to WAV headlessly — the fast iteration loop for ChipAsm authoring without booting the game.

docs

python3 tools/modkit.py docs [--out DIR]

Regenerates the wiki's Reference-Registries.md from src/mods/Schemas.lua (via tools/gen_registry_docs.lua), so the registry reference cannot drift from the engine. The wiki registry reference mirrors that file.