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.
The top level of map.toml
Section titled “The top level of map.toml”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 |
[start]
Section titled “[start]”<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 |
[connections]
Section titled “[connections]”<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 |
[region]
Section titled “[region]”<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 |