Skip to content

map.toml

Generated from tools/pl-assets/src/profile_files.rs by ploom schema map --markdown; do not edit it: cargo xtask bless rewrites it. docs/creating-a-game.md explains the keys with examples; this is the list of all of them, with their types, ranges and defaults.

The build reports every mistake in the file at once, each with its line. A key that is not here is an error.

What one map says that its Tiled file has no place for: its name, music, weather, light, camera, neighbours. All of it is optional. The file is maps/<name>/map.toml.

Pack record: the map’s row of AREAS (name, music, weather, kind, connections), its .pfa header (camera, allow, light, fog, edges, clear, start).

Key Type Without it What it is
name text none: the folder’s name the map’s name as the player sees it: plain text, at most 24 letters
kind "town", "route", "cave", "indoor" "town" what kind of place it is: it sets the default light, the battle backdrop and the banner
music whole number, 0 to 65532, or name of a track of audio/audio.txt, or “none” for silence none: the music is not changed the music that plays here
music_night name of a track of audio/audio.txt, “none” for silence, or “” for its music none: its music the track at night, with game.toml’s [audio.music] night = true (task 25u)
music_seasons list of 4: name of a track of audio/audio.txt, “none” for silence, or “” for its music none: its music in every season the tracks of spring, summer, autumn and winter by [audio.music] season_var; “” is its music
music_flag a flag and a track: [120, "after"] none: none the track while the flag is set, by the rule flag of [audio.music] order
music_region whole number, 0 to 1 0 which of a trainer class’s two eyes tracks plays here ([audio.music] eyes)
travel_music true or false true surfing and cycling play game.toml’s surf and bike tracks here
weather "none", "rain", "snow", "fog", "sand", "sun", "heavyrain", "blizzard", "ash", "diamonddust" none: clear the weather
flags list of 0 to 64: name of a map flag, like “Magnetic” none: none names evolutions and scripts ask of a place (LocationFlag)
script name of a file of scripts/ without .pfs, or “none” none: the file called after the map, when there is one the script module the map runs
banner name of a style of [world.banner.styles] in game.toml, or “none” none: the style of the map’s kind the location banner shown on arrival
camera name of a preset of [camera.presets] in game.toml none: the game’s first preset; with none, the engine’s own camera the camera: a preset of the game’s
allow list of 0 to 4: "run", "cycle", "escape", "fly" none: the engine’s rules for the kind what the player may do here: run, cycle, escape, fly
followers true or false true whether the follower walks on this map
shadows true or false true whether characters cast their shadows on this map
light hour "hh:mm", or name of a table of lights.toml, or day, bright, dim or warm none: day outdoors, bright indoors and in caves where the light comes from: a table, or one hour ("21:00") the day’s light is fixed at
grade colour "#rrggbb" none: white: no colour grading a colour every cell is multiplied by
edges list of 1 to 8 colours "#rrggbb", or false none: the game’s [light] edges outline colours for polygon IDs 0-7, 8-15 and so on (a shorter list repeats its last), or false for none
edges_rear whole number, 0 to 63 none: the game’s [light] edges_rear the polygon ID of the rear plane
fog table, below none: no fog fog that thickens with distance
clear colour "#rrggbb" none: the engine’s clear colour the colour behind everything
shade text none: none a grey picture one pixel larger than the map each way (cell corners), white for full light; a path from the map’s folder
pieces list of 0 to 4096: name of a name in quotes none: the pieces of maps/pieces.toml in its order pieces numbered first, in this order
textures list of 0 to 4096: name of a name in quotes none: in the order pieces use them textures numbered first, in this order
outside name of a ground piece the map has a cell of none: nothing drawn the ground drawn where there is none and past the edge
start table, below none: the map’s start event where a new game begins on this map
connections table, below none: none maps joined at the edges
dive name of a map folder under maps/ none: no map under the deep water the map under this one’s deep water
dark true or false false dark until the flash move is used
variants a list of { map = "name", flag = 7 } or { map = "name", var = [55, 2096] }; a flag or variable by number or by its name in scripts/*.pfsym (var = ["VAR_0x4037", 1]) none: none maps drawn and walked in this one’s place while a flag is set or a variable holds a value, first first; chosen each time the map loads. The map keeps its number, scripts and music; a variant’s map is a folder of maps/ not in maps (tasks 04x, 41g)
battle name of a battle scene of graphics/battle/scenes/ none: the scene named default the backdrop of battles here
battle_ground name of a battle ground of the platforms folder none: by the cell battled on the battle ground
encounters true or false; accepted and not read (wild creatures are placed on the map’s layers) none: nothing an importer’s mark
region table, below none: none where the map lies on the region map (what [maps.NAME] of region.toml says)

<a id=“fog”></a> Fog that thickens with distance: fog = { color = "#c4cad0", start = 29150, shift = 3 }.

Pack record: the map’s .pfa header.

Key Type Without it What it is
color colour "#rrggbb" must be given the fog’s colour
start whole number, 0 to 32767 must be given the depth at which it begins: 0 at the camera to 32767
shift whole number, 0 to 10 must be given how fast it thickens beyond: 0 slowest to 10
slow true or false false it fades in and out at half speed
on true or false true false: it waits for a script to turn it on

<a id=“start”></a> Where a new game begins on the map (a start given in the map’s Tiled file is overridden).

Pack record: the map’s .pfa header.

Key Type Without it What it is
x whole number, 0 to 4095 must be given the cell across
y whole number, 0 to 4095 must be given the cell down
facing "down", "left", "right", "up" "down" the way the player faces

<a id=“connections”></a> Maps joined at this map’s edges.

Pack record: the map’s row of AREAS (connections, offsets).

Key Type Without it What it is
north a map’s name in quotes, or { map = "name", offset = cells } when the neighbour is moved along the shared edge (-127 to 127) none: none the map to the north
south a map’s name in quotes, or { map = "name", offset = cells } when the neighbour is moved along the shared edge (-127 to 127) none: none the map to the south
east a map’s name in quotes, or { map = "name", offset = cells } when the neighbour is moved along the shared edge (-127 to 127) none: none the map to the east
west a map’s name in quotes, or { map = "name", offset = cells } when the neighbour is moved along the shared edge (-127 to 127) none: none the map to the west

<a id=“region”></a> The map’s place on the region map (docs/plans/21-region-map.md): what [maps.NAME] of region.toml would say.

Pack record: the region file.

Key Type Without it What it is
at list of 2: whole number, 0 to 255, then whole number, 0 to 255 none: worked out from a neighbour the square of the grid its north-west corner is on, [x, y]
size list of 2: whole number, 1 to 255, then whole number, 1 to 255 none: worked out from its cells its size in squares, [w, h]
kind "town", "city", "route", "water", "cave", "building", "landmark" none: worked out from the map what the place is
name text none: the map’s name its name on the region map
about text none: none a line about it
icon true or false false an icon marks it
hide true or false false it is not shown
place name of a map folder under maps/ none: worked out from the warps the outdoor map an indoor one belongs to
fly list of 2: whole number, 0 to 4095, then whole number, 0 to 4095 none: the map’s start the cell a flight lands on, [x, y]
path list of 1 to 255: list of 2: whole number, 0 to 255, then whole number, 0 to 255 none: worked out a route’s squares, in order