Skip to content

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.tmj and map.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.

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.

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.

Walking from one zone into another, in this order:

  1. The old zone’s scripts stop; its local flags and variables are cleared.
  2. 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.
  3. The new zone’s script module is in use.
  4. Wild creatures come from the new zone’s tables.
  5. The music changes to the zone’s track, without the fade of a warp; if it is the same track, it plays on.
  6. The weather becomes the zone’s.
  7. The location banner shows, if the game has one and the name changed.
  8. The zone’s on load scripts run, then on enter on 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.

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.

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.

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.

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 side
pc = { script = "pc", facing = "up" } # kind 1: only facing north
script 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 (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.