Map settings
Each map folder holds a map.toml beside its map.tmj. It says what the Tiled file
has no place for: the map’s name, what kind of place it is, its music, camera, light
and weather, the scene its battles are fought in. Every key is optional, so a map with
no map.toml at all is a working map with the engine’s defaults.
This page explains the keys a creator uses most. Every key, with its type, range and default, is in the map.toml reference.
Example
Section titled “Example”The sample’s parlour is a room made by hand, as a creator makes one:
name = "Moss Cottage"kind = "indoor"camera = "interior"allow = []shade = "shade.png"# Indoors the town's music stops.music = "none"And its garden, outdoors:
name = "Back Garden"kind = "town"camera = "default"clear = "#63a54a"music = "town_night"# Battles here are fought in graphics/battle/scenes/meadow.battle = "meadow"Common keys
Section titled “Common keys”| Key | What it does |
|---|---|
name |
The name the player reads: in the location banner, and in a message that names the place. At most 24 letters. Without it, the folder’s name. |
kind |
town, route, cave or indoor. It sets the defaults that follow from the kind of place: the light, the banner style, what the player may do. |
music |
A track of audio/audio.txt by name, or "none" for silence. It starts on arrival, before the map’s scripts run, so a script can still choose another. A map that asks for the track already playing lets it play on. |
script |
Which script file is this map’s. Without it, scripts/<folder>.pfs. Two maps may share a file: the sample’s lab uses script = "station". |
camera |
The camera preset: default, interior, orthographic, or a preset an import wrote. See Cameras. |
allow |
What the player may do here: run, cycle, escape, fly. Without it, the engine’s rules for the kind. allow = [] allows none of them, as indoors. |
light |
Where the light comes from: a light table (day, bright, dim, warm, or one of lights.toml), or an hour ("21:00") the day’s light is fixed at. See Light and weather. |
weather |
The weather the map is entered in, full from the first picture. |
battle, battle_ground |
The battle scene and platforms of battles fought here. See Battles. |
clear |
The colour behind everything, seen past the edge of the ground. |
shade |
A grey picture of baked shade on the ground, one pixel a cell corner. |
followers |
false keeps the following creature out of this map. |
start |
Where a new game begins, instead of a start event: { x = 4, y = 5, facing = "down" }. |
Other keys tune one system: music_night, music_seasons and music_flag for
music rules; grade, fog, edges and dark for
light; dive for the map under deep water and
flags for evolutions that ask where they happen (Game systems);
region for the region map. pieces and textures fix the order the map numbers
its pieces in, which only matters when something refers to them by number.
Why the kind matters: a game has many maps, and most of their settings follow from what the place is. Giving the kind once, rather than the light, banner and travel rules separately, keeps maps consistent and lets the game change a kind’s defaults in one place.
Variants
Section titled “Variants”A place that changes with the story (a room left in a mess after a battle, a town rebuilt) is a second map drawn in the first one’s place while a flag is set or a variable holds a value:
variants = [{ map = "bedroom_mess", var = [55, 2] }, { map = "bedroom_new", flag = 300 }]- Each
mapis a folder ofmaps/with its ownmap.tmjthat is not ingame.toml’smaps. It has no number of its own. - The first variant whose condition holds is chosen each time the map loads: on arriving, through a warp, on a continued save. Nothing changes while the player is on the map. To show the change, set the flag, then warp the player back in.
- The map keeps its number, name, music and scripts. The variant’s ground, pieces and events are the ones used, so give it the same people and warps as the map.
- A map of a joined world that has a variant in force is loaded on its own for that visit.
Variants are swapped at load because a map’s cells and meshes are read once when it
arrives. Changing them under the player’s feet would mean holding two versions in
memory, which the DS cannot spare for a whole map. For one cell, a script’s setcell
does the job instead.
Planned (plan 25): variants chosen by the season, the game’s version or the day of the week, and patches of a map rather than the whole of it.
Location banner
Section titled “Location banner”A game with a [world.banner] table in game.toml shows the map’s name in a
window that slides down when the player arrives, stays a while and slides away.
Without the table there is no banner.
[world.banner]slide_in = 10 # frames the slide takeshold = 60 # frames it staysslide_out = 10warps = "always" # through a door or warp: "always", or only onto a map # of another name ("changed")a_hides = true # A takes it away at once
[world.banner.styles]town = { text = ["centre", 12] } # graphics/ui/banners/town.png, the # name centred 12 pixels downplain = { size = [14, 4] } # no picture: a plain window of the skin
[world.banner.kinds]town = "town"route = "town"cave = "plain"indoor = "none"A style is a picture graphics/ui/banners/<name>.png with the name drawn on it, or,
without a picture, a plain window of the skin. Each kind of map takes a style from
[world.banner.kinds]; a map’s own banner = "plain" (or "none") overrides its
kind. The banner goes at once when the player talks, reads, opens the menu or starts
a battle, and a script’s banner shows it again. A map with no name shows none.
Every key of the banner is under
[world.banner] in the reference.
Connections
Section titled “Connections”[connections]north = "route_1"east = { map = "harbour", offset = -4 } # the neighbour moved 4 cells northConnections are checked (the map must exist) and stored with the map, and the region
map reads them. The field does not walk them: ploom build notes that they are not
built yet. To join maps so the player walks from one to the next, place them in
maps/world.toml; see The joined world.
Planned (plan 28): a consistent set of chunk-aligned connections becomes a world at
build time, so two joined maps need no world.toml.