Scenes
Overview
Section titled “Overview”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.
Implementation
Section titled “Implementation”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 // ...}EngineimplementsGame<P>; the DS program (crates/pl-nds/src/lib.rs) and the desktop’s live-reload wrapper (crates/pl-desktop/src/reload.rs) run anEngine.- 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
matcha 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’s view seam
Section titled “The field’s view seam”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.
Video memory: one owner a region
Section titled “Video memory: one owner a region”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 |
What plan 29 still adds
Section titled “What plan 29 still adds”- Planned (plan 29): menu screens (party, bag, summary, storage and the rest) become
a
Screensscene. 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,enteranduncover,leave), and a step returnsStay,Push,Popwith a value, orReplace, each with aTransition(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 oneExtensiontype per binary; a build without Rust isEngine<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.
World grid
Section titled “World grid”- A map is what a creator writes: a folder with
map.tomland 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. APFA5area is read as a world of one zone (Grid::of_area). maps/world.tomlplaces 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]inmap.tomlbecome placements without aworld.toml.
See the world and the world file reference for the creator’s side.
Streaming
Section titled “Streaming”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.
The zone change
Section titled “The zone change”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 and saves
Section titled “Positions and saves”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.
Budgets
Section titled “Budgets”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).