Skip to content

Platform layer

Every difference between desktop and DS sits behind one trait, pl_platform::Platform (crates/pl-platform/src/lib.rs). The rest of the engine is written once.

Two choices shape it (plan 02):

  • The engine owns the main loop. The platform is a set of services the engine calls, not a framework that calls the engine. On the DS the loop waits for the vertical blank; on desktop the window’s event loop is pumped from inside wait_frame (crates/pl-desktop/src/platform.rs), so the engine’s loop is the same code on both.
  • Static dispatch. pl-game is generic over P: Platform, and Video and Audio are associated types, not &mut dyn. Each program is compiled for its one platform; there are no vtables on the DS.

In outline (see the source for every method and its default):

pub trait Platform {
type Video: Video;
type Audio: Audio;
fn profile(&self) -> Profile { Profile::Ds } // ds or wide (plan 16)
fn wait_frame(&mut self); // next 1/60 s; samples input
fn quit_requested(&self) -> bool;
fn inputs(&self, local: &mut [Input; MAX_LOCAL]);
fn video(&mut self) -> &mut Self::Video;
fn audio(&mut self) -> &mut Self::Audio;
fn open(&mut self, path: &str) -> Result<FileHandle, FsError>;
fn read_at(&mut self, f: FileHandle, offset: u32, buf: &mut [u8]) -> Result<usize, FsError>;
fn close(&mut self, f: FileHandle);
fn save_read(&mut self, slot: u8, buf: &mut [u8]) -> Result<usize, SaveError>;
fn save_write(&mut self, slot: u8, data: &[u8]) -> Result<(), SaveError>;
fn device_read(&mut self, buf: &mut [u8]) -> Result<usize, SaveError>;
fn device_write(&mut self, data: &[u8]) -> Result<(), SaveError>;
fn wall_clock_secs(&self) -> i64;
fn log(&mut self, msg: &str);
fn net_open(&mut self) {}
fn net_send(&mut self, bytes: &[u8]) -> usize { 0 }
fn net_recv(&mut self, buf: &mut [u8]) -> usize { 0 }
}
Service What the engine gets Why it is shaped so
Time wait_frame: one tick, 60 a second Logic runs at a fixed rate on every platform
Input Input { buttons, touch } for each local player, MAX_LOCAL = 2 A DS has one player; a desktop may have two (local co-op, plan 43). Touch is a bottom-screen pixel
Video Loads into video memory, and present(&Frame) once a tick The frame is in DS terms (see rendering)
Audio Music, effects, cries, fanfares, volumes, ducking, mono The rules are shared (below); a backend only starts and stops sounds
Files Read-only files by relative path, read at an offset A cartridge read is a seek: the pack is never loaded whole
Saves One opaque blob per slot The save format is pl-systems’s business, not the platform’s
Device The presentation settings text They belong to the machine, not to a save (plan 42)
Clock Seconds of local time Read once; see below
Log One line of debug text The desktop prints it; the DS sends it to the emulator’s debug output
Network Bytes in and out of one connection Online play (plan 33); the defaults have no network
  • Game logic never reads the clock. pl-game’s Runner takes wall_clock_secs once at tick 0 (or from the input log when replaying) and adds whole seconds of ticks. A replay sees the same clock on any machine.
  • The game never asks whether the network worked. Everything it learns comes from bytes received, which the runner writes into the input log, so a replay of an online session needs no network.
  • “No save storage” is an answer, not a crash. SaveError::NoStorage tells the game to warn the player (on the DS: no SD card, which in melonDS means the DLDI setting is off) instead of failing at the first save.
  • Loads happen when a scene starts, not every frame. Video’s load methods take effect at once; the backend keeps no books. Who owns which part of video memory is decided by the caller through pl_render::Vram.

pl_platform::audio holds what both backends share: the division of the DS’s 16 sound channels between music and effects, Music (fades, a track put aside for a battle, fanfares), which effect gets a channel (SfxSlots) and the sample cache (SampleCache). The Audio trait’s backends only start and stop things. Moving the rules here is what makes the two platforms sound the same; see audio for what a creator writes.

crates/pl-desktop is a std program built on winit (window and keys), softbuffer (a CPU framebuffer on screen), cpal (sound, the sound feature), gilrs (gamepads, the gamepad feature) and xmrsplayer (tracker modules). It uses no GPU API.

File Does
platform.rs The desktop Platform: a window (windowed or full screen) or nothing at all (headless)
layout.rs Where the screens sit in the window: the two DS screens or the one wide screen, scaled by the largest whole number that fits, letterboxed
video.rs Video memory as plain arrays and a 2D compositor that follows the DS’s rules pixel for pixel; the 3D picture comes from soft3d.rs
audio.rs Modules and 8-bit samples mixed in stereo at the DS’s output rate, stepped without interpolation as the DS’s channels do; to a device or to a WAV file
config.rs The config file: key bindings, window layout and the presentation settings, name = value lines
gamepad.rs The first two pads are the two local players
storage.rs Game data files, and saves under the per-user data folder, one folder per game.id
reload.rs Live reload: a saved change to the project is built into the pack and the running game takes it
walk.rs Walks: the game played headless from a list of steps, writing the input log it made
net.rs One TCP socket to the server; --host runs pl-server inside the program

Headless mode (--headless, with --replay, --ticks, --screenshot) has no window and no sound device. It is what golden-image tests and test-nds use on the desktop side (see testing).

crates/pl-nds is the ARM9 program, linked against BlocksDS by cargo xtask build-nds. The ARM7 runs BlocksDS’s prebuilt default binary: no Rust runs there (plan 01).

File Does
platform.rs Input from libnds, game data from NitroFS (nitro:/), saves as fat:/ploom-slotN.sav on the SD card, the device settings as fat:/ploom-device.cfg
video.rs The frame onto the hardware: tiles, maps and palettes copied into the video memory banks, sprites into OAM, the 3D scene’s commands to the geometry FIFO as they are
audio.rs Maxmod plays the modules and samples of the sound bank; effects and cries are read from the cartridge into the sample cache when played
heap.rs The global allocator over the C allocator; with profile, every allocation is charged to the current heap tag
prof.rs The profiling ROM’s clock (two chained hardware timers) and its per-tick rows
panic.rs, text.rs The panic screen and debug text, without core::fmt
net.rs A TCP socket over DSWiFi, with the online feature

nds-sys holds hand-written declarations of the libnds, Maxmod and C functions the DS crates use, each copied from the BlocksDS header it names. Hand-written means an ordinary build needs no libclang; the cost is that a declaration is added only when a crate first needs it.

The platforms may look different and never play differently (two platforms). In the trait’s terms: profile (two DS screens or one wide one), the number of local players, device_read’s settings and the window are the desktop’s own. Everything that reaches logic (input, the clock, network bytes) goes through the runner and into the input log.

  • Pausing on the DS’s lid close: not written and not looked into.
  • The desktop program has never been built or run on Windows or macOS, and CI leaves those builds out on purpose until someone will read the result; all development happens on Linux.
  • Real DS hardware is not a target; melonDS is the reference.
  • Planned (plan 46): pl-desktop and pl-nds become libraries with a generic run::<X>(), so a game with its own Rust links them into its own two programs.