Platform layer
Overview
Section titled “Overview”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-gameis generic overP: Platform, andVideoandAudioare associated types, not&mut dyn. Each program is compiled for its one platform; there are no vtables on the DS.
Services
Section titled “Services”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 |
Rules the trait encodes
Section titled “Rules the trait encodes”- Game logic never reads the clock.
pl-game’sRunnertakeswall_clock_secsonce 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::NoStoragetells 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 throughpl_render::Vram.
Audio rules live in one place
Section titled “Audio rules live in one place”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.
Desktop backend
Section titled “Desktop backend”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).
DS backend
Section titled “DS backend”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.
Differences
Section titled “Differences”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.
Unverified
Section titled “Unverified”- 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-desktopandpl-ndsbecome libraries with a genericrun::<X>(), so a game with its own Rust links them into its own two programs.