Skip to content

Platforms

Platform How a game runs there State
Linux The desktop program, a window showing both screens Built and used every day
Windows The same program Builds are designed for it; never run
macOS The same program Never run
DS emulators A .nds ROM; melonDS 1.1 is the reference Built; every check runs in melonDS
A real DS The same ROM Not a target; never tried

The engine owns the main loop. A platform is a set of services the loop calls: wait for the next frame, read the buttons and the pen, draw a frame, play sound, read the game’s data, read and write saves, read the clock (plan 02). Everything else is written once. Only one crate, pl-game, talks to the platform layer; the battle, world, interface, script and systems crates never do.

The same inputs and the same seed give the same game, frame for frame, on every platform. This is the engine’s central promise, and it is tested, not assumed. cargo xtask test-nds plays recorded sessions on the desktop with no window and in melonDS with no window. Both must write the same log, and their pictures must agree:

  • 2D layers and sprites: equal, pixel for pixel;
  • the 3D scene: at most 1 % of pixels further apart than 16 of 255 in a channel.

How this is possible is the subject of Determinism and the seeded RNG and One description of a frame. In short: no floating point in game logic, one random number generator, input recorded per tick, and a desktop renderer that copies the DS’s drawing rules.

The owner’s rule: the builds “may look different, never play differently” (plan 16, decision 310).

May differ May not differ
Graphical detail: particle counts, draw distance, resolution scale, post-processing Game logic and timing
The screen layout on desktop: two screens stacked, or one wide canvas Rules, battles, the random numbers drawn
Controls on desktop: keyboard and gamepad can be rebound, the pen is a pointer Content: maps, scripts, text, data
What the DS cannot draw is drawn natively there, more cheaply, or not at all Saves: one format, written by the same logic

Each presentation setting declares what it does on DS: the same idea with the DS’s hardware, a cheaper version, or off. A replay played at the lowest and the highest presets must give identical game state at every tick; see Presentation and game state.

Controls. On DS the controls are exactly the originals’. On desktop the defaults are the arrows for the pad, Z for A, X for B, Enter for START and Backspace for SELECT, rebindable in the configuration file. The mouse over the lower screen is the pen. Gamepads are supported in the code; no gamepad has been tried yet.

The wide form. Desktop may instead show one 320×180 canvas, scaled by a whole number to the display (×6 is 1080p). The DS build stays two 256×192 screens and is the default. See One wide screen on desktop.

Planned (decision 321): on desktop, the lower screen is automatic by default: the main screen large, the lower one beside it when a scene needs it.

The DS has 4 MB of main RAM, shared by code, static data and the heap. The engine treats this as a hard limit, not a target (the project’s hard rule 3), and every feature is measured against a budget:

Use Budget
Code and static data (the ARM9 program) 1.5 MB
World heap: map chunks, characters, scripts 512 KB
Battle heap 256 KB
Interface, text and save buffer 256 KB
Asset staging: data on its way to video memory 512 KB
Sound bank in RAM (music 320 KB of it) 512 KB
Stack and slack about 450 KB

cargo xtask size fails a build whose code is over budget; cargo xtask profile-nds measures the heaps in melonDS. Last measured figures are on What is built today.

Why the limit shapes the engine:

  • No standard library, no floats, no formatting in the crates that run on DS. Numbers are fixed point (Fx), and messages the player sees are string IDs.
  • Tables of plain functions instead of trait objects and closures: code size on DS matters more than elegance. Every battle effect is a row in a static table.
  • Data read on demand. Maps stream in as the player walks; sound effects load when played; only the parts of a battle’s data it needs are in memory.
  • No dropping content to fit. When something does not fit, the engine is optimised; a creator is never asked to cut content or use a toolchain to save memory (plan 09).

Keeping to the DS’s limits also keeps the desktop build small and fast, and an accurate emulator enforces the same limits anyway (plan 00).

Today, from a clone of the repository:

You want Command
Play on desktop with live reload ploom run, inside the project
A desktop folder to give a player ploom build desktop
A DS ROM cargo xtask build-nds --project DIR (needs the DS toolchain)
The ROM opened in melonDS cargo xtask run-nds --project DIR

Planned (plan 13, plan 26): ploom build nds from prebuilt runtimes, with no Rust and no DS toolchain on the creator’s machine. See Building and shipping.

Said plainly, so nobody relies on it:

  • The desktop program on Windows or macOS.
  • The ROM on real DS hardware.
  • Desktop sound through a sound device: the mixer’s output is checked from WAV files; nobody has heard it through speakers.
  • A gamepad.
  • The project’s CI on its remote host: its first run has not been observed.