ploom CLI
ploom is the one command a creator uses. It turns a folder of ordinary files into a
game, runs it, and checks it. ploom help (or ploom alone) prints the same list as
this page, from the program itself.
Project discovery
Section titled “Project discovery”Most commands work on a project (the picture tools sheet, battle-pic and fit,
and schema, need none). The project is the nearest
folder, at or above the current folder, that holds a game.toml (or, for a tile-map
project without one, a tiles.toml). This is how cargo and git find their
folders, so a creator can run ploom build from any subfolder of the game.
-C <dir> (or --project <dir>) names the project instead. It may come before the
command or among its arguments; both mean the same:
ploom -C games/my-game buildploom build -C games/my-gameOnly new and import take the project’s folder as a plain argument, because the
folder they write does not exist yet (decision 295). Outside a project, a command stops with
“not inside a PokeLoom project” and names both ways out.
A command prints its report on success. On failure it prints ploom: and the
problem, with the file and the place where there is one, and exits with a failure
code, so scripts and editors can use it.
Projects
Section titled “Projects”| Command | Arguments and flags | Reads | Writes |
|---|---|---|---|
ploom new <folder> |
--title <title>: the game’s title (default: the folder’s name) |
nothing | A small working project in a new, empty folder: two maps, placeholder pieces and a character, two scripts and the text, the Tiled tilesets |
ploom build |
--out <folder> (default pack/); --loose: also every file of the pack beside it; --maps <a,b,...>: convert only these maps; --battle-ext <file>: the game crate’s battle tables |
The whole project | pack/game.pak, pack/game.sym, the build state in .ploom/; with Rust of its own, build/report.json |
ploom build desktop |
--out <folder> (default dist/) |
The project, the desktop program | A folder a player runs with nothing else installed: the program named after the game, data/, audio/ |
ploom run |
-- <options>: passed to the desktop program |
The project | The pack, then runs the game and converts each saved change into it |
ploom check |
none | The whole project | Nothing. Every problem with its file and place, and what each map costs against the DS’s limits |
ploom check --art |
--preview <folder>: write a before-and-after picture of each picture whose colours change |
Every picture | Only the previews, when asked |
ploom schema |
[game|map|world|lights] --markdown |
nothing | Prints the reference of every key of that settings file |
ploom tiles |
none | maps/pieces/ |
maps/pieces.tsj, maps/markers.tsj and the thumbnails Tiled shows |
ploom build converts only what changed since the last build: a map is converted
again when its file or a piece it uses changed. The first build converts everything.
With --maps, the other maps are kept as the pack has them; a full build converts
them again. Maps are converted several at once; the environment variable
PL_BUILD_JOBS says how many (default up to 4). The pack is never checked in: it is
made from the project (see Building and shipping).
A project with a Cargo.toml is a game with Rust of its own. ploom build runs its
crate to get its battle tables (kept in build/battle.pfext), puts them in the pack,
and lists what the game changes of the engine’s battle and what it adds (see
Your own battle mechanics).
ploom build desktop names the game by id in game.toml, else by the folder. The
same name keeps the game’s saves apart from every other game’s.
ploom run looks for the desktop program beside ploom. Options after -- go to
it unchanged; the useful ones for a creator:
| Desktop option | What it does |
|---|---|
--profile ds|wide |
Two DS screens, or one 320×180 screen (One wide screen) |
--scale N, --side-by-side, --fullscreen |
Window size and screen layout |
--preset NAME, --set ROW=VALUE |
Presentation preset and rows (Presentation settings) |
--hour HH:MM, --date YYYY-MM-DD |
Start the clock at that time, to see the light of an hour |
--record FILE, --replay FILE |
Write the session’s input log; play one back |
--save-dir DIR |
Where saves go |
ploom run -- --hour 19:30 --scale 3While the game runs, saving a map, a piece, a picture, the text or a script updates it. Window keys: Tab (held) runs fast, P pauses, N steps one frame while paused, F12 takes a screenshot, F11 switches between window and whole screen.
Pictures
Section titled “Pictures”These three take files, not a project: they work on any picture.
| Command | Arguments and flags | What it does |
|---|---|---|
ploom sheet <in.png> <out.png> |
--from engine|rpgmaker|rpgmaker-vx|gba; --frame <w>x<h> |
Converts a character sheet to the engine’s 128×128 sheet of four rows of four frames; with --frame, an engine sheet to frames of that size |
ploom battle-pic <in.png> <out.png> |
--kind creature|trainer |
Makes a plain picture a battle picture: background cut out, margins trimmed, made smaller if over the limit (creature 96×96, trainer 64×80), 15 colours and clear |
ploom fit <in.png> <out.png> |
--kind sheet|trainer|creature|texture |
Writes the picture beside how it looks after the DS’s colour fit |
ploom sheet hero-vx.png graphics/characters/hero.png --from rpgmaker-vx--from names the source layout: engine (the default) and rpgmaker are four
rows of four frames (Essentials and RPG Maker XP; rpgmaker also cuts out a plain
background); rpgmaker-vx is VX, MV and MZ’s three columns; gba is nine frames
side by side, as the generation-3 games draw them. See Art.
Fetching data
Section titled “Fetching data”Creature data and pictures are never in the repository (hard rule 1). These commands
fetch them onto the creator’s machine. Each keeps a cache (the user’s cache folder,
or $PL_CACHE) so it runs once with a network and afterwards offline.
| Command | Arguments and flags | Reads | Writes |
|---|---|---|---|
ploom fetch-data |
--version <commit>: the Showdown commit (default: the project’s lock, else the commit the engine is checked against); --latest: today’s published files, not pinnable; --cache <folder>; --offline |
Pokémon Showdown’s data files over HTTPS | external/showdown-data/, showdown-data.lock |
ploom fetch-pbs <folder> |
--into <folder> (default external/pbs) |
A folder of PBS text files you supply | A copy in external/pbs, which git ignores |
ploom pack |
--showdown <folder>; --pbs <folder> (repeatable, base first); --id-table <file>; --out <file>; --release; --allow <id>; --coverage; --coverage-dir <dir>; --battle-ext <file> |
Showdown’s data, PBS folders, or both | pack/game.pak and the symbol file pack/game.sym |
ploom fetch-sprites |
--species <a,b,...>; --community; --cries; --style gba|ds; --expansion <folder>; --cache; --offline; --i-know |
The project’s data; picture servers | graphics/creatures/, graphics/items/, graphics/types/, with fetched.toml and CREDITS.md; with --cries, audio/cries/ |
ploom fetch-trainers |
--set <a,b,...> (default gen4dp,gen4,gen4pt); --as <class=file,...>; --cache; --offline; --i-know |
The built pack’s trainer classes; Showdown’s sprite server | graphics/trainers/<class>/front.png |
ploom fetch-data && ploom buildploom pack compiles only the creature data; ploom build calls it, so a creator
rarely runs it alone. Which data it reads is set by data = "showdown", "pbs" or
"both" in game.toml; without it, what the project has is used. With both,
Showdown’s data covers everything a battle reads and the PBS files add what Showdown
lacks (catch rates, yields, prices, trainers, encounters). --release refuses moves
and abilities the engine does not implement; --allow lets one through (* for
all). See Creatures, moves and data.
fetch-sprites and fetch-trainers fetch pictures that belong to Nintendo, Game
Freak and The Pokémon Company. They are for a game you do not share: never commit
them, never ship them. Both refuse to write into a folder git does not ignore unless
given --i-know. --community adds pictures drawn by the community, whose authors
ask for credit; give it only after reading the credits it writes.
Importing
Section titled “Importing”| Command | Arguments and flags | Reads | Writes |
|---|---|---|---|
ploom import <rom> <project> |
--stage <list>: only these stages; --force: redo every stage |
A DS ROM you own | A project: the ROM unpacked in .ploom/import, each stage’s files, import/report.md, assets under assets/<source>/<family>/<role>/, the art set art/<source>/ |
ploom import --decomp <tree> <project> --profile gba-emerald |
--play <steps> |
A GBA decompilation tree (pret’s layout) | A tile-map project: tilesets, maps, joined edges, warps, people, scripts and text |
ploom import-midi <song.mid> <instruments.txt> <out.xm> |
--volume N |
A MIDI file and a list of instruments | A tracker module for audio/music/ |
ploom sync <source> |
--overlay <folder> (default overlay/) |
Another project and this one’s overlay | This project: the source’s files with the overlay laid over them |
ploom source add <name> <path> |
--profile P |
A ROM, a decompilation or a project | A row in sources.toml; its image in the per-user cache |
ploom source |
none | Every source in sources.toml |
Their images, refreshed when changed |
ploom source list |
none | sources.toml |
Prints the sources, their images and what each draws |
ploom restyle --maps A,B |
--start MAP,X,Y; --pad N; --like KIND=MAP (repeatable) |
The content source, a tagged tile-map game | 3D maps of this project that place the same roles |
ploom import ~/roms/platinum.nds ~/games/pt-importAn import may be run again. Only what changed is redone; text files you edited are
merged, other edited files get the new version beside them as .imported. It refuses
a folder git would commit from, because the result holds the game’s own data. Files
in the project’s import/ folder steer it: maps.toml (where a new game begins, how
many maps), text.toml (rewrapping lines), tags.toml (your corrections of asset
roles). See Importing games and
Import a game you own.
sync makes a game that tells another project’s story on its own data: everything
of the source but what a build makes is copied, then the overlay’s files go on top.
The overlay’s game.toml and text.txt hold only the keys that change. An overlay
reskin.toml maps pieces, textures and pictures to another project’s look. Run
ploom build afterwards.
source and restyle belong to style chains: drawing one game’s world in another’s
art. See Asset roles and style chains.
Assets
Section titled “Assets”| Command | Arguments and flags | What it does |
|---|---|---|
ploom assets |
--source S, --family F, --role R, --kind K, --confidence C, --untagged, --find TEXT, --json |
Lists the project’s organized assets, one line each, or as JSON |
ploom assets tag <asset> <role> |
none | Corrects an asset’s role in import/tags.toml; the next import moves it |
ploom assets sheet |
the filters above; --out FILE |
One contact sheet PNG of the matching assets’ previews (default assets/sheets/<source>-<role>.png) |
ploom catalogue [<source>] |
--kind K, --role R, --find TEXT, --json |
The same over every kind of asset, maps included |
ploom assets --role tree --source pt--role tree matches the role and every role under it (tree.small, tree.row).
--confidence takes a word (creator, behaviour, label, curated, name,
use, colour, made, strongest first); W.. means that word and every weaker
one, ..W that word and every stronger one.
Prototypes
Section titled “Prototypes”ploom decomp-diff <tree> [--names <file>] compares an imported Platinum’s events
with those read from its decompilation’s source. It is a prototype for the source
route of plan 26, not listed in ploom help.
Planned
Section titled “Planned”| Command | What it does | Plan |
|---|---|---|
ploom test |
Runs the game’s battle scenario tests (.pbt) and walks without Rust |
plan 34 |
ploom test --official |
Plays a corpus of battles on official identifiers and checks the game changed nothing it did not declare | plan 34 |
ploom check --rust |
Lints a game’s or a package’s crate for desktop and DS | plan 46 |
ploom add <git-url>[@tag] | <path> |
Fetches a package, checks it, copies it into packages/, locks it in ploom.lock |
plan 46 |
ploom remove <name> |
Removes a package; refuses while another requires it | plan 46 |
ploom update [<name>] [--to <version>] |
Fetches newer versions within the required ranges | plan 46 |
ploom packages |
Lists the packages: version, source, what each adds | plan 46 |
ploom eject builtin:<name> |
Copies a built-in package into the project as the creator’s own | plan 46 |
ploom build nds |
A .nds from ploom alone, with a prebuilt DS runtime: no Rust, no DS toolchain |
plans 13 and 26 |
Today a ROM is built from the repository with
cargo xtask build-nds --project <dir>, which needs the DS toolchain (see
Install).
Contributor commands
Section titled “Contributor commands”Engine contributors run cargo xtask <command> in the repository. These are not part
of the creation kit. See Testing and Budgets.
| Command | What it does |
|---|---|
cargo xtask test |
Host tests of every crate; a crate is skipped when it passed and nothing it depends on changed (--no-cache tests all) |
cargo xtask build-desktop |
The desktop program, release build |
cargo xtask build-nds |
The DS ROM of the sample; --project demo or --project DIR for another project, --replay FILE for a ROM that plays an input log |
cargo xtask run-nds |
Builds the ROM and opens it in melonDS |
cargo xtask test-nds |
Plays the same input logs on desktop and in melonDS with no window; both must report and show the same. NAME..., -j N, --list, --no-cache; --project DIR --replay FILE for a game of your own |
cargo xtask test-weather, test-sound, test-part1 |
Parts of test-nds: the weather sessions, the sound check, the demo’s part 1 |
cargo xtask size |
DS code and static data against the budget; --by-crate [N] for the largest crates and functions |
cargo xtask profile-nds |
Runs profiling ROMs in melonDS and prints where time and memory go |
cargo xtask data |
Builds the packs of the sample and the demo |
cargo xtask bless |
Rewrites every generated file the tests compare, then lists what changed |
cargo xtask pairs |
Compares the real games and ours at the same place and hour (Fidelity by pairs) |
cargo xtask new-project and the other *-project commands |
Make the test projects that test-nds sessions play |