Rust extensions
Most of a game needs no Rust. Maps, pieces, pictures, creature data, trainers, text, menus’ layouts, rules and options are data; events, cutscenes, puzzles and most custom logic are scripts. Rust is for what the engine cannot express in either: a new battle effect too intricate for a script hook, a new script command that does real work, a screen or minigame of its own.
The engine has two languages, its script language and Rust, and no third (decision 325). A game’s Rust is compiled into its programs; nothing is loaded at run time, on desktop or DS. That keeps one game the same game on both platforms and inside the DS’s memory budget.
Overview
Section titled “Overview”| You want | Route | Where |
|---|---|---|
| a move from existing effects, a new type, a changed number | data | Creatures and data |
| a rule that runs on a battle event, a scaled team, a forced shiny | a script hook | Custom mechanics, Scripts and events |
| an ability, item or move effect of your own, or a built-in one changed | Rust: the battle tables | below |
| a script command that does real work, a screen, a minigame | Rust: the Extension | planned, below |
Each route is declared and reported by the build. Built-in mechanics are checked against Showdown; a game’s own or overridden ones are the game’s responsibility, and its scenario tests cover them (decision 230).
A project with a Cargo.toml is a game with Rust of its own. The template is
templates/game-crate in the repository. Its library is the game’s Rust, built for
the DS and the desktop alike; its small binary prints the game’s battle tables for
the build.
The template adds three invented effects:
- a new ability that powers up the holder’s moves of its own first type at a third of its HP or less;
- a new move of a new type whose data (power, type, accuracy) is PBS and whose effect is Rust;
- an override of a built-in ability, so this game’s version gives half again instead of double. The engine’s own row is untouched: other games and the conformance runs still reach it.
An effect is written as the engine’s are: plain functions in static tables of handler rows, one row per battle event it reacts to. A sketch of the template’s ability:
fn ember_heart_base_power(battle: &mut Battle<'_>, ctx: &mut EventCtx) -> Relay { let user = &battle.mons[ctx.mon() as usize]; let low = user.hp as u32 * 3 <= user.max_hp() as u32; if low && battle.active_move.data.ty == user.types[0] { return ctx.chain_modify(3, 2); } Relay::Undef}
static EMBER_HEART: [Handler; 1] = [Handler::on(EventId::BasePower, ember_heart_base_power).priority(5)];The game gives the engine one type with one static table, its BattleExt: new
abilities, items and moves, their names, and its overrides. The engine’s dispatcher
gathers, sorts and calls the game’s rows exactly as it does its own; only their
numbers differ.
ploom build on a project with a Cargo.toml runs the crate’s binary
(cargo run -- --battle-ext) and keeps its tables in build/battle.pfext, or reads
the file --battle-ext <file> names. Then:
- a PBS ability or item whose
Effectnames one of the game’s effects gets the game’s number, and a move’s behaviour the game’s callbacks; - the build lists what the game changes of the engine’s battle and what it adds, on
the terminal and in
build/report.json; - the pack records a content version mixed from the engine’s and the game’s tables, so a pack built for another game crate is refused, as one built for another engine is.
The crate’s own tests (tests/scenarios.rs in the template) build the pack from its
PBS files with these tables and play battles with and without them, on the host. Today
that is where a game’s battle tables run: neither the desktop program nor the DS ROM
links a game’s crate yet. Planned (plan 46): ploom build compiles the game’s own
desktop program and DS ROM with its crate inside.
A game’s Rust follows the engine’s rules, because it runs inside the same deterministic loop on a machine with 4 MB of RAM:
| Rule | Why |
|---|---|
#![no_std] with alloc |
the same crate builds for the DS |
No floating point (float_arithmetic = "deny" in the template’s lints); fixed point through Fx |
the DS has no FPU, and floats can round differently on two machines |
| Random numbers only from the battle’s own generator (later, the game’s) | the same inputs and seed must give the same battle everywhere, which replays and conformance rest on |
No core::fmt in hot or size-sensitive code; messages are string IDs |
code size on DS |
| Static tables of plain functions; no trait objects, closures or generics per effect | code size on DS |
| No allocation every frame | the game loop’s budget |
Changing any item of the battle’s creator API is a breaking engine change, recorded as a decision, so a game crate’s code keeps compiling between versions.
Script commands
Section titled “Script commands”A command a game adds in Rust is declared in a symbol file of scripts/,
ext.pfsym by custom, with its number, its parameters and whether it gives a value:
ext dig_site = 0 (x, y) -> valueext stamp = 2 (kind)ext chime = 7Scripts then use it as any command:
dig_site 4, 7var(0) = dig_site(x: 4, y: 7)stamp 3This compiles today. Every argument is a number and must be given; a command without
-> value cannot be used in an expression. Until a game supplies the Rust side,
every ext command answers 0. Planned (plan 46): importers name the commands the
engine lacks as ext commands too, so a creator can fill an imported game’s gaps one
command at a time.
Planned (plan 46): the Rust side. A command is a row of plain functions, run and an
optional busy for one that waits. Its context gives flags, variables, saved records,
the party and boxes, the bag, money, currencies, text registers, the game’s random
numbers and clock, and nothing of the field’s internals. ploom build writes
scripts/ext.pfsym from the crate, so the numbers never drift.
Extension
Section titled “Extension”Planned (plan 46, after Z-Moves and Dynamax in plan 36): one Extension per game, a
list of parts (the game’s crate and each package’s), each a set of static tables:
- battle: today’s
BattleExt, unchanged; - commands: the
extcommands above; - scenes: full screens of the game’s own (a minigame, a custom menu) opened from a script and returning a value to it, drawn in 2D through the engine’s layers and sprites;
- apps: small apps for the lower screen’s gadget;
- hooks: Rust handlers for every script hook, run in a fixed order with the scripts’;
- triggers: new event kinds that scripts hook with
on NAME(args), checked at most once a step, never every frame; - records: declared saved records, the same that scripts read and write, so a save made with one build of the game loads in the next.
ploom build writes a small glue crate that links the game’s crate and its packages’
into the game’s own desktop program and DS ROM. A game without Rust is unchanged: the
prebuilt programs, no toolchain. A game with Rust needs rustup and the pinned
toolchain, which ploom names with the command to run; it never installs anything
itself.
Budgets on DS. A game’s parts together may use 128 KB of ARM9 code and static data
and 64 KB of heap. ploom build nds reports each part’s bytes; past the budget it
warns, past the whole program’s budget it refuses (Limits).
Planned (plan 46): ploom new --rust to start a game crate, ploom check --rust to
lint it for both targets, and, on desktop only, ploom run --watch to rebuild the game
when the crate changes and resume where you were by replaying your inputs.
Limitations
Section titled “Limitations”A few parts of a game are still made by the engine’s own tools rather than from pictures and text, though none needs a game crate:
- The font (
graphics/ui/font.pff) is copied as a ready-made file. - The skin’s buttons, gauges, icons and idle picture are copied; its window and
text-box frames can be pictures (
graphics/ui/skin/window.png,frame_<n>.png). - The DS sound bank is built by the engine’s DS build, which needs the DS toolchain (Building and shipping).