Skip to content

Architecture

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

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.

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-core
pl-battle pl-core
pl-script pl-core
pl-data pl-battle (optional, the `battle` feature)
pl-world pl-core, pl-render
pl-ui pl-render
pl-systems pl-core, pl-data, pl-battle
pl-net pl-core, pl-battle
pl-platform pl-render
pl-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-sys
pl-desktop pl-game, pl-platform, pl-present, pl-render, pl-world, and host tools

Why the rule holds:

  • Logic is tested on the host. A crate that cannot reach a platform can be tested with cargo test and a fake (pl-script’s Host, pl-battle’s Dex). Most bugs are meant to be caught there, not in the emulator.
  • Logic is the same on both platforms. If pl-world could ask the platform anything, it could ask something whose answer differs between desktop and DS. Everything from outside reaches the logic through pl-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.rs reads every manifest and fails if one does. Inside pl-game only the view builders receive the settings; the replay proof in present_tests.rs checks 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.

Every crate under crates/ except pl-desktop builds for the DS and follows the same rules (AGENTS.md, “Code conventions”).

  • #![no_std] with alloc. The DS has no operating system. The heap is the C allocator of the SDK behind a GlobalAlloc (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 and pl-gpu), never in logic.
  • No core::fmt in 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 static array of Handler rows, each a fn pointer; a script command is a row of pl_script::ops; an importer stage is a Stage of two fn pointers. 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-game is generic over P: Platform, so each program is compiled for exactly one platform with no vtables. The menu screens and the scenes are enums matched by hand.

The engine owns the loop; the platform is a set of services it calls (plan 02). pl_game::Runner::run does, each tick:

  1. Platform::wait_frame (the vertical blank on DS, 60 Hz pacing on desktop);
  2. read each local player’s input, or the next tick of an input log;
  3. record it if asked;
  4. call Game::tick, which updates and presents the frame;
  5. 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.

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 (plan 42): crates/pl-gpu, a std desktop-only renderer on wgpu that reads the same pl_render::Scene. Plan 00’s line “every crate under crates/ except pl-desktop runs on the DS” then also excepts pl-gpu, and a test fails if wgpu appears under pl-nds.
  • Planned (plan 46): crates/pl-ext, the facade a game or package crate depends on, and an Extension in pl-game that carries a game’s battle tables, script commands, scenes, apps and hooks. pl-desktop and pl-nds become libraries with a generic run, and a build without Rust is run::<NoExt>().