Building
A project is a folder of text and picture files. A player never sees it. What a
player gets is a pack (one file, game.pak, holding everything the game reads)
beside a program that plays it: the desktop program, or the DS program inside a
.nds ROM. The same pack runs on both.
ploom buildploom build converts everything in the project (maps, pieces, pictures, sprites,
text, scripts and the creature data) into <project>/pack/game.pak, and writes beside
it game.sym (the numbers the build gave names, for tools and scripts) and game.id
(below). The pack is built, never edited and never checked into git: anyone with the
project folder can make it again, byte for byte.
Why a pack at all? The DS has 4 MB of RAM and reads from a cartridge. Text, PBS and Tiled JSON would cost memory and time to parse there, so all of it is turned on your machine into records the DS reads in place, on demand. Names become numbers; pictures become DS textures and tiles; scripts become bytecode (The pack format).
The first build converts everything; after that, only what reads a changed file. Some options:
| Option | Does |
|---|---|
--maps <a,b> |
converts only those maps and keeps the others as the pack has them |
--loose |
also writes every file of the pack beside it under its own name |
--out <folder> |
writes the pack somewhere else |
--battle-ext <file> |
a game crate’s battle tables (Rust extensions) |
Maps are converted several at once; PL_BUILD_JOBS says how many. ploom check
converts everything and writes nothing: every problem with its file and place, and
what each map costs against the DS’s limits (Limits). ploom run
builds and starts the desktop game with live reload. All subcommands are on the
command reference.
Desktop
Section titled “Desktop”ploom build desktopThis builds, then writes a folder a player can run with nothing else installed
(<project>/dist unless --out <folder> says otherwise):
| In the folder | What |
|---|---|
| the program, named after the game | the desktop runtime, copied |
data/ |
game.pak and game.id |
audio/ |
the game’s music and sounds |
No sources and no symbols go in: only what a player needs. The program finds data/
beside itself, so it starts from a file manager. Building again replaces the folder’s
contents rather than adding to them.
The desktop runtime is the pl-desktop program that sits beside ploom. Today you
build both from the source repository (cargo xtask build-desktop; see
Install), so shipping a game needs Rust on your machine but not on
the player’s. Planned (plan 26): release downloads of ploom with the runtimes
prebuilt for each operating system, so a creator needs no Rust either. The desktop
program has been run on Linux only; Windows and macOS builds have never been run.
Game id and saves
Section titled “Game id and saves”Every game’s saves are its own. id in game.toml names the game (lower-case
letters, digits, - and _); without it, the project folder’s name does. The build
writes it to game.id beside the pack, and the desktop program keeps that game’s
saves in a folder of that name under the per-user data folder:
| System | Saves |
|---|---|
| Linux | ~/.local/share/ploom/<id>/ (or under XDG_DATA_HOME) |
| macOS | ~/Library/Application Support/ploom/<id>/ |
| Windows | %APPDATA%\ploom\<id>\ |
Do not change id once players have saves: the game would look for them in a new
folder. Two games on one machine never share a save.
DS ROM
Section titled “DS ROM”Today a ROM of a project is made by the engine’s own build, from the source repository, with the DS toolchain installed (Install):
cargo xtask build-nds --project path/to/mygameIt writes path/to/mygame/mygame.nds, never under the repository’s target/.
cargo xtask run-nds --project path/to/mygame builds it and opens it in melonDS.
The ROM holds the DS program, the pack and the DS sound bank. The sound bank is the
one part of a game’s data still made by the DS toolchain, which is why that toolchain
is needed today even for a game with no Rust.
A game that passes ploom check is meant to fit the DS: the check counts every view of
every map and video memory per map against the same limits the DS program has
(Limits). The engine itself is checked the other way:
the same input logs are played on desktop and in melonDS, and their logs and pictures
must match (Testing).
Planned (plan 13, plan 26): ploom build nds writes game.nds itself, around a
prebuilt DS program, with the sound bank made without the DS toolchain, so a creator
with only a release download can make a ROM. ploom run nds then opens it in the
emulator the creator configures.
Planned (plan 46): a game with Rust of its own is built into its own desktop program
and DS ROM by ploom build, with the game’s crate linked in. A game without Rust keeps
the prebuilt programs.
Licensing
Section titled “Licensing”The engine and its sample ship no Nintendo assets and no official creature data, and what you ship is your responsibility. In short:
- Your own work (maps, models, pictures, music, text and data you made or have the
right to use) is yours to ship. Credit third-party art as its licence asks, as the
engine’s repository does in its
CREDITS.mdfor the community creatures the sample uses;ploom fetch-spriteswrites aCREDITS.mdfor what it fetches. - An imported game is built from your own copy of a game and is for your own use. Do not distribute its project, its pack, its desktop folder or its ROM (Importing games).
- Official pictures and data fetched to your machine (
ploom fetch-sprites,ploom fetch-trainers,ploom fetch-data) are for a game you do not share. The picture commands say so, and refuse to write into a folder git does not ignore unless told otherwise. - Games with real Pokémon go online only on a private server.
Planned (plan 40): ploom build --share refuses a pack that holds any asset read from
a ROM or a decompilation, naming each; a project that mixes such sources is shared
only as a hack file, which players apply to their own copies of the games.
Updates
Section titled “Updates”A new build of a game replaces data/ (or the ROM); the saves stay in their folder. A
save records the build hash of the pack it was made with, and holds things by number:
an update that renumbers items, species, flags or maps can break players’ saves, so
add new things after the old ones rather than between them. Planned: a save remapped
by identifier when the pack has changed (decision 97, waiting for the owner), and
declared saved records remapped by name (plan 46).