Skip to content

Scenes

The first game loop was one object, Field, with the title, the battle, the menu screens and the ending as its fields and flags; Field::tick decided by hand which ran. Each new mode made that worse. Plan 29 (decision 208, one of four approved rewrites) replaces it with a small stack of scenes, each owning its heap and its video memory, statically dispatched.

The DS games do the same: the field is one application among others, and a battle or a menu runs as its own. PokeLoom differs in one way on purpose: it keeps the field loaded under a battle rather than tearing it down, which is cheaper within the engine’s measured budget.

crates/pl-game/src/engine.rs:

pub enum Scene {
Title(Box<Title>), // the title screen, Continue, the intro
Battle(Box<Fight>), // pushed when the field asks for one
Ending(Ending), // the endgame fade, the challenge mode's game over
}
pub struct Engine {
field: Box<Field>, // always the bottom scene
above: Vec<Scene>, // at most MAX_ABOVE = 3, top last; room taken once
// ...
}
  • Engine implements Game<P>; the DS program (crates/pl-nds/src/lib.rs) and the desktop’s live-reload wrapper (crates/pl-desktop/src/reload.rs) run an Engine.
  • The field is always the bottom scene. Other scenes draw over a field, loaded or not. The title’s field has nothing loaded yet.
  • An enum matched by hand, not trait objects: one match a tick, no vtables, and each variant boxed once when pushed, so nothing is allocated per frame.
  • A battle is pushed when the field asks for one and popped with its outcome, which the field reads (Field::end_battle). While it runs nothing of the field runs; the field’s textures survive under it.
  • The session (session.rs) is what lives for the whole run: the pack’s files, the party, bag and save, the scripts’ flags, variables and machine, and the interface’s fixed parts (fonts, skin, talk box, start menu). Every scene reads it.
  • The engine holds the presentation settings and hands them only to the drawing code (see presentation and state).
  • The engine’s digests (world, scripts, battle) are what replays and co-op compare.

The field holds what both field styles share: the world, zone changes, warps, the camera’s target, script hooks, wild steps. What it draws with is one seam:

pub(crate) enum StageView {
Grid, // 3D chunks, characters as cards, the camera rig
Tiles(Box<crate::tileview::TileStage>), // a tile map on 2D layers, characters as sprites
}

A map’s header chooses the view when it loads. The tile-map style (GBA-style games, plan 24) is the same field with the other view: scripts, warps, menus and battles are shared, not duplicated. See the tile-map style.

pl_render::Vram keeps books only; the rule of who owns what is the engine’s:

Region Owner
The session’s fixed reserve (font, frames, talk box) the session, always at the same places
Texture memory and texture palettes the lowest scene that draws 3D (the field). A battle above it books none, so the field’s textures survive
Top screen 2D the top scene; a scene uncovered loads its own again
Bottom screen the top scene if it owns it, else the session’s panel
  • Planned (plan 29): menu screens (party, bag, summary, storage and the rest) become a Screens scene. Today they are a stack inside the field’s interface (hud.rs), itself an enum of boxed screens matched by hand, the pattern the engine grew from.
  • Planned (plan 29): every scene answers the same five calls (tick, covered, draw, enter and uncover, leave), and a step returns Stay, Push, Pop with a value, or Replace, each with a Transition (Cut, Fade, Curtain, Battle). The stack runs every transition, with today’s exact tick counts, so no replay changes.
  • Planned (plans 29 and 46): Scene::Ext, a game crate’s own scenes. The engine becomes generic over one Extension type per binary; a build without Rust is Engine<NoExt> and pays nothing. A script opens such a scene and waits for its value. An extension scene draws 2D only, through a narrow drawing interface, and never sees the field’s internals.
  • A map is what a creator writes: a folder with map.toml and a Tiled map, a rectangle of 32 × 32-cell chunks. Its number is the identity scripts, warps, saves and the region map use.
  • A zone is a map seen from inside a world: its header (name, music, weather, encounters, script module, rules, banner) and its events. One map is one zone.
  • A world is a set of maps on one plane of cells, with one drawing set: textures, prop meshes, light table, fog, edges and camera preset. A map in no world is a world of one zone.

Why: the DS games keep the outdoor world as one grid and change only the zone as the player walks over a border. Loading maps one at a time showed the clear colour past every edge of an imported game. What changes at a zone border is the same short list in every game studied; what does not change is the drawing set.

  • An area file (PFA5, crates/pl-world/src/area.rs): a header, a shared section (props, warps, actors, spots, camera zones, sheets, light and edges) and a directory of chunks. Cells are 32-bit: behaviour, height in half levels, a tag, encounter and battle ground.
  • A world file (PFA6, crates/pl-world/src/grid.rs): a matrix of 8-byte slots (a chunk, a zone, an altitude, a variant index reserved for map variants), the world’s textures and meshes, a zone table, and the chunk bodies unchanged. A PFA5 area is read as a world of one zone (Grid::of_area).
  • maps/world.toml places maps: origins in cells, multiples of 32 in the 3D style, because the chunk is the unit of storage and streaming. The build refuses another origin and names the nearest aligned one. Two maps may not own the same chunk. Consistent [connections] in map.toml become placements without a world.toml.

See the world and the world file reference for the creator’s side.

Area keeps at most MAX_LOADED = 4 chunks: the player’s chunk and the nearer neighbour on each axis, a 2 × 2 window, with one more arriving. A chunk arrives a piece a tick, so no tick reads much. The window runs over the world’s matrix, so the neighbouring maps are drawn because their chunks are in it. Shared prop meshes load with the first resident chunk that names them and drop with the last.

Field::enter was split in two (crates/pl-game/src/field.rs):

Step When Does
load_world a warp to another world, a new game, Continue, live reload open the world, its drawing set, the window, the camera rig; then change_zone
change_zone load_world, and every step onto a cell of another zone the fixed list below

change_zone stops the old zone’s scripts and clears map-local flags; swaps the zone’s people (the player and follower stay); takes the new zone’s script module; sets encounters, whereabouts and the region map’s visit; changes music without a picture fade; sets weather; shows the location banner if the name changed; runs on load, then on enter on the next tick.

On a walk it never fades, reloads textures, rebuilds the camera rig, changes the light table or resets effects.

No hitch at the border. A zone’s events and script module are read ahead into a staging buffer when its first chunk enters the window (Field::stage_zones, at most two zones staged), so the crossing copies and never reads the cartridge. Measured on the DS on imported Platinum: the crossing went from 102 ms to 14 ms, under one frame (decision 276).

The tile-map style keeps its own storage (a whole tile map is small, and GBA-style maps join by edges at any offset), but crossing into a connected map calls the same zone change.

Positions inside a world are world cells; a save stores the place by map number and cell. A world of 30 × 30 chunks (960 cells a side) fits an i32 in Fx with room to spare.

The window is unchanged from before the world grid: four chunks and one arriving. The world adds its matrix (8 bytes a slot), the zone table and at most two staged zones. The world heap budget is 512 KB; see budgets.

  • Planned (plan 25): map variants (a map’s chunks swapped by a flag or variable, seasons, changed places) use the matrix slot’s reserved variant index. Today a variant swaps a whole map’s file at load (decision 298).