Table of Contents

The modkit CLI

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

The modkit CLI

tools/modkit.py is the mod-author command line: scaffold, validate, lint, gen2check, pack, bounce, docs, set-github, add-release-workflow. 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
python3 tools/modkit.py scaffold my_mod --github owner/repo --experimental

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, --github owner/repo (optional; enables launcher auto-update — see Manifest), --experimental (off until the player confirms enable), --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.

github is optional: if the field is missing, validate prints a tip that setting "github": "owner/repo" enables launcher auto-update. A present but malformed value is an error.

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.

set-github

python3 tools/modkit.py set-github my_mod owner/repo
python3 tools/modkit.py set-github my_mod https://github.com/owner/repo

Writes or updates the optional github field on an existing manifest.json (for mods scaffolded before the field existed). Same normalization as the loader: owner/repo or a github.com URL.

add-release-workflow

python3 tools/modkit.py add-release-workflow my_mod
python3 tools/modkit.py add-release-workflow my_mod --force

Copies the standard GitHub Actions release workflow into mods/<id>/.github/workflows/release.yml, stamped with the mod's id. On each push to main (or a manual run) it packs a root-level installable .zip and publishes a GitHub Release — the layout the launcher's Import mod .zip / Update / Versions paths expect. Use --force to overwrite an existing workflow. See Publishing.

Home

Start here

Concepts

Tutorials

Reference

Guides

Playing

Engine 1.0.0 · mod API 2 · repository · Discord

This project ships no ROM data. All game content is decoded on the player's machine from their own verified Pokemon Red ROM; mods ship recipes and original assets, never extracted content.