Skip to content

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.

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"
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.

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:

maps/bedroom/map.toml
variants = [{ map = "bedroom_mess", var = [55, 2] }, { map = "bedroom_new", flag = 300 }]
  • Each map is a folder of maps/ with its own map.tmj that is not in game.toml’s maps. 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.

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 takes
hold = 60 # frames it stays
slide_out = 10
warps = "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 down
plain = { 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]
north = "route_1"
east = { map = "harbour", offset = -4 } # the neighbour moved 4 cells north

Connections 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.