Skip to content

Frame model

The engine does not call a graphics API. Each tick it fills a description of what the two screens should show, in the DS’s own terms: tile layers, sprites and one 3D scene. A backend takes that description and puts it on a screen.

Backend What it does with the frame
DS (pl-nds) Maps it onto the hardware almost one to one: layer settings to the 2D engines’ registers, sprites to their attribute memory, the 3D scene to the geometry engine
Desktop (pl-desktop) Draws it in software, imitating the hardware: 256×192 a screen, 15-bit colour, the DS’s layer and sprite rules, a 3D rasterizer ported from melonDS’s
Planned (plan 42): pl-gpu Reads the same 3D scene and draws it with a GPU, adding shadow maps, water and other modern effects on desktop

The game logic writes one description and is done. It never knows which backend will draw it.

The types are in pl-render, a crate with no standard library, shared by both backends. In outline:

pub struct Frame<'a> {
pub screens: [ScreenFrame<'a>; 2], // top and bottom
pub scene: Option<&'a Scene<'a>>, // the 3D scene, drawn in place of layer 0
pub hold_scene: bool, // keep showing the last scene drawn
pub scene_below: bool, // the 3D scene on the lower screen instead
}
pub struct ScreenFrame<'a> {
pub layers: [Layer; 4], // four tile layers: scroll, priority, on or off
pub sprites: &'a [Sprite], // at most 128
pub affine: &'a [Affine], // shared scale-and-rotate settings
pub brightness: i8, // fade: -16 black, 0 unchanged, 16 white
pub blend: Blend, // how translucent sprites mix
}

The 3D Scene holds a camera, a list of mesh instances, a list of billboards (flat characters), the clear colour, and the DS’s 3D features as the hardware has them: fog, edge marking, anti-aliasing and the four hardware lights.

What is not in the frame: tiles, tile maps, palettes, textures and sprite pictures. Those live in video memory, loaded when a scene starts (entering a map, opening a menu, starting a battle). The frame only says which of them to show and where. That keeps a frame small and cheap to fill every tick, and it is how the DS itself works.

Sprite and tile-map entries even use the DS’s own bit layout, so on DS they are copied to the hardware unchanged.

A thin DS backend. If the description matched a desktop graphics API, the DS backend would have to translate everything, every frame, on a 67 MHz processor. In DS terms there is nothing to translate.

The same pixels on both. The desktop renderer applies the DS’s rules: the same layer priorities, the same palette limits, the same sprite sizes, the same fixed-point 3D maths and rasterization, the same clipping. So the desktop shows what the DS will show. A creator sees the DS’s limits on their desktop, not on a console later.

Comparable. Because both draw the same description by the same rules, their pictures can be compared. test-nds requires 2D layers and sprites to be equal pixel for pixel, and the 3D scene to have at most 1 % of pixels more than 16 of 255 apart in a channel. (Plan 03 first allowed “indistinguishable at a glance” for 3D; matching melonDS’s rules made it far closer.)

Headless. The software renderer needs no window and no GPU, so it runs in tests: golden images, replays and the pairs tool all use it.

No driver differences. Three desktop operating systems and their GPU drivers cannot disagree about a picture drawn on the CPU. A frame of 2,048 polygons at 256×192 is little work for a desktop processor.

The cost is that the frame can only express what the DS can draw. Modern effects belong to the planned GPU renderer, which reads the same scene and adds to it, never to the description the logic fills (plan 42).

Logic runs at a fixed 60 ticks a second on every platform. Each tick:

  1. Read the input (the Tick: each player’s buttons and pen, and the clock).
  2. Update the game: the world, scripts, battle, menus.
  3. Fill the Frame for both screens.
  4. The backend presents it. On DS the loop waits for the vertical blank; on desktop it paces itself to 60 Hz.
  5. Update the audio.

Everything that decides the game happens in step 2. Steps 3 and 4 only read the game. That one-way order is what lets the desktop draw differently from the DS (a wide canvas, more particles, modern effects) without the game playing differently. See Presentation and game state.

The 3D field at 30 frames a second. The 3D overworld redraws its scene every second tick, as the reference games do: it matches their feel and halves the DS’s 3D load. Between, the frame sets hold_scene, and the last scene drawn stays on screen. Menus, 2D layers and battles update at 60. The world’s logic still runs every tick; only the 3D picture is held.

The polygon budget. The DS draws at most 2,048 polygons a frame and drops the rest. The engine logs a warning when a scene sends more than a safe number, and ploom check measures each map’s views against the limit before the game runs.

A presentation profile says how big a screen is. It changes no logic, timing, script or save.

Profile Screens Where
Ds two of 256×192, the pen on the lower one DS, and the desktop’s default
Wide one of 320×180, scaled by whole numbers Desktop only

On DS the profile is fixed when the program is built, so asking it costs nothing. See One wide screen on desktop.