World
There are two ways from one map to another. A warp is a door, a stair, a hole: the picture fades, the next map loads, the picture comes back. A joined world has no fade: maps lie side by side on one plane, the next map is already drawn past the edge, and walking over the border changes only what belongs to the place. Outdoors the DS games join their towns and routes this way; indoors they use warps. PokeLoom does both.
- A map is what you draw: a folder with
map.tmjandmap.toml. Its name stays how warps, scripts and saves refer to it. - A world is a set of maps placed on one plane of cells, drawn with one set of textures, one light table, one clear colour and one fog.
- A zone is a map seen from inside a world: its name, music, weather, people, scripts and wild creatures. One map is one zone.
A map in no world is a world of one zone. That is every map of the sample.
world.toml
Section titled “world.toml”maps/world.toml places maps in worlds, each by its north-west cell:
[world.vale]maps = { town = [0, 32], hill = [64, 32] }This would place the sample’s 64 × 64 town and its 32 × 32 hill side by side, the hill’s west edge against the town’s east edge. (The sample does not do this; its hill is reached through the garden’s gate by a warp.)
The build holds a world to these rules, and its errors name the maps and the fix:
- An origin is a multiple of 32 cells. The chunk, 32 × 32 cells, is the unit the engine stores and streams, so a map must start on a chunk’s edge. The error gives the nearest origin that is.
- Two maps may not own the same chunk. A map may leave chunks of its rectangle empty, so an L-shaped place is a map whose empty corner a neighbour fills.
- The light table, grade, clear colour, fog and edges are equal across a world’s maps. A world is drawn with one set; a map that differs is an error that says to make them equal or give that map a world of its own.
- The camera may differ. Each zone keeps its own camera preset, and walking into a zone of another camera eases into it.
- A world is at most 255 chunks across and down. A map is in one world at most, and a map the game does not list is left out.
Every key is in the world.toml reference. Importers write this file for the games they read.
Streaming
Section titled “Streaming”The engine keeps the player’s chunk and the nearer neighbour on each axis in memory: a window of 2 × 2 chunks, with one more arriving. As the player walks, chunks ahead are read and chunks behind are dropped, one piece a tick. Neighbouring maps are drawn because their chunks are in the window, not because they are loaded whole. The data of a zone about to be entered (its events and scripts) is read ahead while its first chunk comes into the window, so the step over the border reads no file.
This is why a world of any size fits in the DS’s 512 KB world heap: only four chunks and what stands on them are ever resident.
Zone borders
Section titled “Zone borders”Walking from one zone into another, in this order:
- The old zone’s scripts stop; its local flags and variables are cleared.
- The old zone’s people go and the new zone’s come. People exist only while the player is in their zone. The player and the follower stay.
- The new zone’s script module is in use.
- Wild creatures come from the new zone’s tables.
- The music changes to the zone’s track, without the fade of a warp; if it is the same track, it plays on.
- The weather becomes the zone’s.
- The location banner shows, if the game has one and the name changed.
- The zone’s
on loadscripts run, thenon enteron the next tick.
What never changes on a walk: no fade, no new textures, no new light table. The DS games keep the same split: the drawing set belongs to the world, the rest to the place.
A warp is a warp object on a map’s events layer:
| Property | Meaning |
|---|---|
to |
The map’s name, or back |
to_x, to_y |
The cell to arrive on |
facing |
Which way the player faces on arriving |
kind |
How it is taken and played (below); without it, auto |
enter |
The one direction that takes it, for arrow and stairs |
The sample’s garden has a warp at cell (16, 21) with to = "parlour", to_x = 10,
to_y = 8 and facing = "down": the parlour’s back door.
Kinds of warps
Section titled “Kinds of warps”Without a kind the cell decides: a door piece makes the warp a door, a stairs
cell a stair, anything else a mat.
kind |
Taken by | Played |
|---|---|---|
door |
Stepping into the doorway | The door opens, the player steps in, it shuts; the fade |
mat |
Stepping on it | The fade |
stairs |
Stepping on it | A slow step, a slow fade |
walk |
Stepping on it | The player walks a cell as the picture fades, and a cell out on the far side |
arrow |
Standing on it and pressing its enter direction |
The fade |
hole |
Stepping on it | Gone, the fade; on the far side a fall, a thud and a shake |
ladder |
Stepping on it | A climb out of sight; a climb up on the far side |
escalator |
Stepping on it | A slow ride on and off |
panel |
Stepping on it | A spin up and away; a spin down |
teleport |
Stepping on it | Turns on the spot, then up; down, then turns |
The sample’s weir has a panel by the pool up to the hill, and the hill an arrow
warp back.
Each kind’s timing and look are settings of the game, in game.toml: a table a kind,
setting only what differs from the engine’s look. The sample changes only the panel’s
sounds:
[world.warps.panel]sound = "whistle"arrive_sound = "hop"Fades, colours, rises, drops, turns and the shake on landing are keys of the same
table; see [world.warps.<kind>].
Importers write each original game’s looks here, so the same engine plays each game’s
warps as that game does.
Warps back to where you came from
Section titled “Warps back to where you came from”to = "back" leads to the cell the player stepped onto a warp from, facing away
from it. Use it for a lift, a cable car, or a room with several ways in: one warp out
serves them all. It needs no to_x and to_y.
Entrance cameras
Section titled “Entrance cameras”A camera zone (see Cameras) drawn over a warp’s cell and the cell it is arrived on gives the doorway a framing of its own. Arriving there the camera starts at the zone’s framing and eases back to the map’s as the player walks out of the zone; walking onto the warp it eases in again. This is how generation-5 games move the camera at doors.
Furniture
Section titled “Furniture”A bookshelf, a PC, a bin, a town map on the wall: things the player presses A at,
each kind running the same script wherever it stands. A cell of behaviour contact
is furniture: it cannot be walked onto, and A facing it runs a script of
scripts/common.pfs. Its kind is its tag (the tag layer; no tag is kind 0), and
the kinds are listed in game.toml, numbered from 0 in the order written:
[world.contacts]bookshelf = { script = "bookshelf" } # kind 0: from any sidepc = { script = "pc", facing = "up" } # kind 1: only facing northscript bookshelf { sign "Books on weather, tides and knots."}A sign or a person on the cell comes first. This puts one script behind every bookshelf of a game, rather than one event on each.
Planned
Section titled “Planned”Planned (plan 28): [connections] in map.toml become world placements at build
time, so two maps joined edge to edge need no world.toml; a set that does not line
up on chunks is an error that suggests writing one.
Planned (plan 28, plan 24): the tile-map style keeps its own edge joins (its maps may join at any offset) but crosses them with the same zone change, so people, music, weather, banner and scripts behave the same in both styles.
Planned (plan 25): a light or grade per zone inside one world, as generation-5 games light each area apart.