mod-workbench

A small helper for developing ZeroSpades weapon/resource mods. It works on uncompressed mod folders so there is no zip/pak round-trip while editing: change a file, relaunch, see the result. When a mod is ready, pack it into a distributable .pak with one command.

Everything is driven by workbench.py — a single Python 3 script with no dependencies (standard library only; no virtualenv, no pip). It runs on macOS, Linux, and Windows.

Quick start

./workbench.py --setup                      # one-time: detect paths, set author
./workbench.py --new-mod MyMod              # seed a mod from vanilla content
# ...edit files under MyMod/...
./workbench.py --try MyMod                  # launch the game with the mod live
./workbench.py --build MyMod                # pack it into <Author>-MyMod.pak

On Windows, invoke it through the Python launcher: py workbench.py --setup.

Commands

--setup [author]

Generates the local .env. Detects the ZeroSpades userdata directory for your platform, reads the engine binary path from SPConfig.cfg (core_executablePath), and records an author name. The author defaults to your git config user.name; pass it as an argument or accept the prompt.

It also asks whether new mods should be set up as their own git repository (init + initial commit) automatically. The answer is stored as GIT_INIT_MODS in .env, so --new-mod / --new-from-userdata apply it without prompting each time. Edit that value (yes/no) any time, or re-run --setup.

Run this once. Re-run it after building/moving ZeroSpades so the recorded binary path stays current. If the path comes up empty, launch ZeroSpades once (so it writes its config) and run --setup again.

--list-userdata-mods

Lists the mods currently installed in the ZeroSpades userdata Mods/ folder, showing both loose paks ([pak]) and unpacked folder mods ([folder]).

--new-mod <name>

Creates name/ seeded with the full vanilla content — every shipped pak is extracted and merged into the folder, ready to edit without any repacking. Also writes a MODINFO.txt (name, author, date) and, per your --setup choice (GIT_INIT_MODS), sets the mod up as its own git repository.

--new-from-userdata <name.pak> [newname]

Unpacks an already-installed pak from the userdata Mods/ folder into an editable workbench folder, so you can iterate on an existing mod. The folder is named after the pak (suffix dropped) unless newname is given. Also applies your GIT_INIT_MODS choice. See --list-userdata-mods for the available pak names.

--try <name>

Launches ZeroSpades with the mod folder mounted on top of the vanilla resources (via the engine's --try-mod). No packing, no install — edit files in the folder and re-run to see the change immediately.

--build <name>

Packs the mod folder into a distributable .pak (a zip) at the repository root, named <Author>-<name>.pak (e.g. Nuceto-MP5K.pak). The author is taken from the mod's MODINFO.txt, falling back to the .env author; if neither is set, the file is just <name>.pak.

The archive mirrors the mod folder at its root, so it drops straight into a userdata Mods/ install. Workbench-only files are left out: MODINFO.txt, .DS_Store, the mod's .git/ repository, and .gitignore.

--vscode

Sets up AngelScript autocompletion for VS Code. Generates an as.predefined file at the workspace root from the engine's shipped API declarations (Scripts/Reference/*.as inside pak999-References), and writes .vscode/extensions.json recommending the AngelScript Language Server (sashi0034.angel-lsp). Open this folder as the VS Code workspace so the single as.predefined covers every mod below it; editing any mod's .as files then gets type-aware completion and go-to-definition for the ZeroSpades scripting API.

Mods are separate repos

The workbench's .gitignore ignores everything at the root except its own tooling, so mod folders are never tracked here. Instead, --new-mod and --new-from-userdata run git init inside the new mod (with an initial commit), giving each mod its own version history. This is controlled by the GIT_INIT_MODS preference chosen at --setup; set it to no to leave new mods untracked.

Requirements

• Python 3 (no extra packages).
• A built/installed ZeroSpades, run at least once so it records its config.
• git is optional — used only for per-mod repositories and the default author.