Skip to content

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.

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:

Terminal window
ploom -C games/my-game build
ploom build -C games/my-game

Only 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.

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
Terminal window
ploom run -- --hour 19:30 --scale 3

While 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.

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
Terminal window
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.

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
Terminal window
ploom fetch-data && ploom build

ploom 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.

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
Terminal window
ploom import ~/roms/platinum.nds ~/games/pt-import

An 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.

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
Terminal window
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.

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.

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).

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