Architecture
Overview
Section titled “Overview”The engine is a Cargo workspace (Cargo.toml at the root). Members are crates/*,
tools/*, templates/*, xtask and conformance.
| Layer | Crates | Runs on |
|---|---|---|
| Foundations | pl-core, pl-data, pl-render, pl-prof, pl-present |
DS and desktop |
| Logic | pl-battle, pl-script, pl-world, pl-ui, pl-systems, pl-net |
DS and desktop |
| The game | pl-game |
DS and desktop |
| Platform | pl-platform (the trait), pl-desktop, pl-nds, nds-sys |
one each |
| Tools | pl-cli (ploom), pl-assets, pl-pbs, pl-showdown, pl-scriptc, pl-import, pl-packs, pl-samplekit, pl-server |
host only |
| Development | xtask (cargo xtask ...), conformance (needs Node) |
host only |
A game is not a crate. It is a project folder (sample/, demo/) of text, maps and
pictures that the tools build into a pack. A game that needs Rust adds a crate made
from templates/game-crate (see Rust extensions).
Engine crates
Section titled “Engine crates”| Crate | Owns |
|---|---|
pl-core |
Fx (an i32 with 12 fractional bits), the one RNG (Showdown’s “gen5” generator), FNV-1a state hashes, ids, small collections |
pl-data |
The pack: reader (no_std) and writer (the std feature), record layouts (records.rs), the battle data a fight loads (battle.rs) |
pl-render |
The frame in DS terms (Frame, ScreenFrame, Scene), geometry commands (gx.rs), meshes and textures, fog, light through the day, video memory books (Vram), profiles |
pl-prof |
Timing sections and heap tags for the profiling ROM; empty types without the on feature |
pl-present |
Presentation settings: rows, presets, the device file (plan 42) |
pl-battle |
Battle rules, a port of Showdown’s simulator: queue, dispatcher, effects, gimmicks, the extension tables of a game crate |
pl-script |
The script bytecode (ops.rs), the module format, flags and variables, the Host trait, the machine |
pl-world |
Maps as chunks, cells, heights, the world grid and zones, movement, characters, the camera rig, doors and ground effects |
pl-ui |
Text, windows and menus drawn as DS background tiles; feel constants measured from the reference |
pl-systems |
Party, storage, bag, encounters, evolution, the sectioned save file; logic only |
pl-net |
The online protocol: messages, frames of at most 256 bytes, the link battle’s lockstep |
pl-game |
The engine: the main loop (Runner), the Engine and its scenes, the field, battles on screen, menu screens, the script host |
pl-platform |
The Platform trait and its services: video, audio, input, files, saves, clock, network |
pl-desktop |
The desktop program: a window or headless, the software renderer soft3d, live reload, walks |
pl-nds |
The DS program (ARM9), linked against BlocksDS |
nds-sys |
Hand-written declarations for libnds, Maxmod and the C library |
Each crate’s lib.rs opens with a module comment that says the same at more length.
Read it before changing the crate.
Dependencies
Section titled “Dependencies”The rule from plan 00: pl-battle, pl-world, pl-ui, pl-script and
pl-systems never depend on a platform crate. Only pl-game talks to pl-platform.
As built, the arrows run like this (each crate lists only its direct engine
dependencies):
pl-core (none)pl-render pl-corepl-battle pl-corepl-script pl-corepl-data pl-battle (optional, the `battle` feature)pl-world pl-core, pl-renderpl-ui pl-renderpl-systems pl-core, pl-data, pl-battlepl-net pl-core, pl-battlepl-platform pl-renderpl-game all of the above, pl-present, pl-prof; pl-net only with `online`pl-nds pl-game, pl-platform, pl-render, pl-prof, nds-syspl-desktop pl-game, pl-platform, pl-present, pl-render, pl-world, and host toolsWhy the rule holds:
- Logic is tested on the host. A crate that cannot reach a platform can be
tested with
cargo testand a fake (pl-script’sHost,pl-battle’sDex). Most bugs are meant to be caught there, not in the emulator. - Logic is the same on both platforms. If
pl-worldcould ask the platform anything, it could ask something whose answer differs between desktop and DS. Everything from outside reaches the logic throughpl-game, which records it in the input log (see determinism). - Presentation never reaches logic. No logic crate may depend on
pl-present, directly or through another crate.xtask/tests/present.rsreads every manifest and fails if one does. Insidepl-gameonly the view builders receive the settings; the replay proof inpresent_tests.rschecks the rest (see presentation and state).
pl-world and pl-ui depend on pl-render for its plain types (MeshInstance,
tile map entries). They describe what to draw; they never draw.
pl-desktop is the one engine crate allowed std, and the one that depends on host
tools: pl-assets and pl-scriptc for live reload, pl-server to host a link battle
from the game. None of that is reachable from pl-nds.
Constraints
Section titled “Constraints”Every crate under crates/ except pl-desktop builds for the DS and follows the same
rules (AGENTS.md, “Code conventions”).
#![no_std]withalloc. The DS has no operating system. The heap is the C allocator of the SDK behind aGlobalAlloc(crates/pl-nds/src/heap.rs). Nothing in a hot path allocates per frame.- No floating point. The ARM9 has no FPU; software floats are slow and large, and
their results can differ by platform. All maths is integer or
Fx, whose format is the DS 3D hardware’s own, so values go to the hardware unchanged. Floats are allowed only on the desktop side of plan 42 (the post chain andpl-gpu), never in logic. - No
core::fmtin hot or size-sensitive paths. Formatting machinery costs tens of kilobytes of code on the DS. User-visible text is string IDs; the DS panic handler prints only plain strings (crates/pl-nds/src/panic.rs). - Static tables of plain functions instead of trait objects, closures and a
generic per effect. A battle effect is a
staticarray ofHandlerrows, each afnpointer; a script command is a row ofpl_script::ops; an importer stage is aStageof twofnpointers. A trait object brings a vtable per type; a generic per effect brings a copy of the code per effect. On a machine where code sits in 4 MB of RAM, code size matters more than elegance. - Static dispatch where a trait is needed.
pl-gameis generic overP: Platform, so each program is compiled for exactly one platform with no vtables. The menu screens and the scenes are enums matched by hand.
Main loop
Section titled “Main loop”The engine owns the loop; the platform is a set of services it calls (plan 02).
pl_game::Runner::run does, each tick:
Platform::wait_frame(the vertical blank on DS, 60 Hz pacing on desktop);- read each local player’s input, or the next tick of an input log;
- record it if asked;
- call
Game::tick, which updates and presents the frame; - update audio.
The game’s clock is the platform’s clock at tick 0 plus the ticks run, so a replay
sees the same clock on any machine. Implementors of Game<P> are the engine
(pl_game::engine::Engine), the 3D test program (pl_game::demo) and the interface
gallery (pl_game::gallery). Test programs stay out of a game’s ROM: pl-nds has
them only with the test-programs feature.
The engine itself, its scenes and the field are described in scenes and the world.
Features
Section titled “Features”Cargo features decide what a binary carries, so a DS ROM pays only for what the game uses:
| Feature | Crate | Off means |
|---|---|---|
online |
pl-game, pl-nds, pl-desktop |
no networking code, no pl-net, no Wi-Fi ARM7 binary |
sign-board, style-window-menu, style-one-screen-party |
pl-game |
that menu style is not in the ROM; the game’s record is drawn in the engine’s own style |
test-programs |
pl-nds |
the ROM runs only the game |
profile |
pl-nds (turns on pl-prof/on) |
no timing, no heap tags, no allocation headers |
sound, gamepad |
pl-desktop |
no cpal, no gilrs (both need system packages on Linux) |
| Tool | What it does |
|---|---|
pl-cli |
The ploom command (see the command reference) |
pl-assets |
Converters (images, OBJ models, Tiled maps, audio, layouts) and the incremental project build that writes game.pak |
pl-pbs |
The data model shared by every data source, the PBS front end, the pack compiler and its coverage report |
pl-showdown |
A second front end to the same model: Showdown’s published data, read without executing it |
pl-scriptc |
The script compiler, and the generator of the script language reference |
pl-import |
ploom import: a ROM or decompilation into a project (see the importer) |
pl-packs |
Builds the packs of sample/ and demo/ for tests, which are not checked in |
pl-samplekit |
The sample game’s original kit made by code |
pl-server |
The multiplayer server (ploom-server), also embedded in the desktop program |
Tools are std and host only. No crate that runs on the DS depends on one.
Planned
Section titled “Planned”- Planned (plan 42):
crates/pl-gpu, astddesktop-only renderer onwgputhat reads the samepl_render::Scene. Plan 00’s line “every crate undercrates/exceptpl-desktopruns on the DS” then also exceptspl-gpu, and a test fails ifwgpuappears underpl-nds. - Planned (plan 46):
crates/pl-ext, the facade a game or package crate depends on, and anExtensioninpl-gamethat carries a game’s battle tables, script commands, scenes, apps and hooks.pl-desktopandpl-ndsbecome libraries with a genericrun, and a build without Rust isrun::<NoExt>().