Platforms
Overview
Section titled “Overview”| 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.
Parity
Section titled “Parity”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.
Differences
Section titled “Differences”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.
Memory limit
Section titled “Memory limit”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).
Building
Section titled “Building”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.
Unverified
Section titled “Unverified”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.