game.toml
Generated from tools/pl-assets/src/profile.rs by ploom schema --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.
ploom check reports every mistake in game.toml at once, each with its line. A key that is not here is an error.
The top level of game.toml
Section titled “The top level of game.toml”The groups of game.toml. A group left out is the engine’s defaults.
| Key | Type | Without it | What it is |
|---|---|---|---|
game |
table, below | its keys’ defaults | the game’s identity and maps |
world |
table, below | its keys’ defaults | the field |
light |
table, below | its keys’ defaults | light and outlines |
text |
table, below | its keys’ defaults | text |
rules |
table, below | its keys’ defaults | rules a new game starts with |
hall |
table, below | none: as many teams as the save holds | the Hall of Fame (task 11k) |
time |
table, below | none: no TIME record: the engine’s defaults |
the clock |
battle |
table, below | its keys’ defaults | the battle’s presentation and sound |
ui |
table, below | its keys’ defaults | menus and screens |
audio |
table, below | none: no AUDIO record: the engine’s sounds and music |
the interface’s sounds and the music’s lowering (task 25k) |
content |
table, below | none: an original game | the source the game’s story comes from (plan 40) |
style |
table, below | none: the project’s own art alone | where each family’s look comes from (plan 40) |
graphics |
table, below | none: no GRAPHICS record: auto, every row offered, no caps |
the presentation settings a player starts at and may choose (plan 42) |
coop |
table: present means on, below | none: one player | several players in one field (plan 43, task 33c) |
limits |
table, below | none: the platform’s, and the DS’s while the DS is a target | what the game may use at run time (plan 48) |
camera |
table, below | none: no CAMERAS record: every map has the engine’s own camera |
the field’s cameras (task 28g) |
[game]
Section titled “[game]”<a id=“game”></a> The game’s identity and its maps.
Pack record: GAME (start; test_start is a bit of flags); id is the file game.id beside the pack; targets is in LIMITS.
| Key | Type | Without it | What it is |
|---|---|---|---|
id |
word, 1 to 64 of a-z 0-9 - _ |
none: the project folder’s name | the folder its saves are kept in, apart from every other game’s; do not change it once players have saves |
title |
text | "" |
the game’s title |
maps |
list of 0 to 4096: name of a map folder under maps/ | none: every folder of maps/ that holds a map.tmj, in alphabetical order | the map folders, in the order the engine numbers them |
start |
name of a map folder under maps/ | none: the first of maps |
the map a new game starts on, at its start event |
test_start |
true or false | false |
a new game chosen with SELECT held starts on the map teststart; leave it out of a game you release |
data |
"showdown", "pbs", "both" |
none: found: Showdown’s data when fetched, pbs/ when there |
the creature data ploom build uses |
targets |
list of 1 to 2: "desktop", "ds" |
none: ["desktop", "ds"] |
the platforms the game is made for (plan 48): ["desktop"] alone lifts the DS’s budgets (each is a note, not an error) and the DS build refuses the game; the desktop is always one |
[world]
Section titled “[world]”<a id=“world”></a> The field: how the world is drawn and walked.
Pack record: GAME (followers is a bit of flags); the field-moves file fieldmoves.bin.
| Key | Type | Without it | What it is |
|---|---|---|---|
picture |
list of 2: whole number, 8 to 256 | none: the whole screen | a tile-map field’s picture in pixels, width and height, when smaller than the screen: centred with a black border, the talk box, questions and the Start menu kept inside it (a GBA game’s 240 x 160); whole tiles, centred on a tile (task 39e) |
character_south |
whole number, 0 to 15 | 0 |
sixteenths of a cell a character’s card stands south of (in front of) its cell’s middle, its shadow on the cell |
character_size |
whole number, 8 to 64 | 32 |
units (sixteenths of a cell) a 32-pixel frame of a person spans, across and up (Black’s 28) |
pace_rest |
whole number, 0 to 254 | 16 |
frames (1/30 s) a person who paces stands at each end of its beat, one who walks a circuit at each corner, and one who spins between turns (Emerald’s 0) |
jump_lift |
list of 16: whole number, 0 to 255 | none: the engine’s own arc, 11 units at its highest | units (sixteenths of a cell) a jump lifts a character’s picture at each of 16 steps, from the first frame to the landing; a jump of any length steps through them at its own rate (task 27j) |
character_dip |
whole number, 0 to 16 | 0 |
units a person’s card is drawn lower as the camera tilts down: this times one less the cosine of the tilt, at most half of it (Black’s 4) |
character_facing |
true or false | false |
characters’ cards face the camera, as generation 4’s billboards, instead of standing upright: a frame is its rows on the screen wherever it stands, and a card leans back over the cell behind (decision 36) |
antialias |
true or false | false |
the field is drawn with the DS’s anti-aliasing, as generation 4’s fields are: a polygon’s left and right edges are mixed with what is behind them by how much of each pixel they cover, and a marked edge (edges) half and half |
see_through_rear |
true or false | false |
the 3D picture’s rear plane is empty, as generation 4’s fields clear it: where the scene draws nothing its clear colour shows as the screen’s backdrop, and a polygon’s anti-aliased edge over nothing keeps its own colour instead of being mixed with the clear colour |
sort_translucent |
true or false | false |
see-through polygons are drawn sorted by their bottom, then top, rows on the screen, as the DS’s automatic sort (the reference games’ fields); else in the order the engine sends them |
shadow |
table: present means on, below | none: opacity 19, the shadow’s own size, all day | the shadow under the characters by the hour (task 41a) |
banner |
table: present means on, below | none: no location banner | the location banner (task 25i) |
warps |
table, below | none: every kind of warp the engine’s look | how each kind of warp is played (task 25n) |
contacts |
table of at most 256 named entries, below | none: no furniture cells | the kinds of furniture cell (behaviour contact), numbered in the order written from 0 (task 25q) |
followers |
table: present means on, below | none: nobody follows | the party’s lead walks behind the player |
field_moves |
table, below | none: each move by its default identifier, with no badge | what does each field move |
fishing |
table: present means on, below | none: no fishing: fish is -4 and rods do nothing |
fishing: the cast, the bite, the press in time (task 25v) |
[world.shadow]
Section titled “[world.shadow]”<a id=“world-shadow”></a> The shadow under the characters by the hour (task 41a): a row an hour of the day it changes at, the first row also before its hour. Generation 4 widens it by day and fades it at night.
Pack record: SHADOW (28 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
hours |
list of 1 to 6: whole number, 0 to 23 | must be given | the hours its rows start at, rising |
alpha |
list of 1 to 6: whole number, 0 to 31 | must be given | its opacity from each hour, 0 to 31 |
width |
list of 1 to 6: whole number, 0 to 255 | must be given | its size across (x) from each hour, in sixteenths of its own |
depth |
list of 1 to 6: whole number, 0 to 255 | must be given | its size along (z) from each hour, in sixteenths of its own |
offset |
list of 3: whole number, -128 to 127 | none: three units up on the cell’s middle: [0, 48, 0] | where it lies from the cell’s middle, east, up and south, in sixteenths of a unit (generation 4’s [-8, 16, 32], Black’s [0, 16, 0]) |
[world.banner]
Section titled “[world.banner]”<a id=“world-banner”></a>
The location banner (task 25i, crate::banner): its timing in frames, when it shows, its styles and the style of each kind of map. Present means on.
Pack record: BANNER, BANNER_STYLES, AREA_BANNERS, and a banner_NNN.pfn file a style with a picture.
| Key | Type | Without it | What it is |
|---|---|---|---|
delay |
whole number, 0 to 255 | 0 |
frames between arriving and the slide in |
slide_in |
whole number, 0 to 255 | 10 |
frames the slide in takes |
hold |
whole number, 1 to 65535 | 120 |
frames it stays |
slide_out |
whole number, 0 to 255 | 10 |
frames the slide out takes |
travel |
whole number, 0 to 255 | 0 |
pixels the board travels, from out of sight to in view (0: its own height) |
step |
whole number, 0 to 255 | 0 |
pixels it moves a frame (0: its travel spread over the frames) |
every |
whole number, 0 to 255 | 0 |
frames between updates; every count above is then in updates (0: every frame) |
edges |
"changed", "always" |
"changed" |
over a map’s edge: only onto a map of another name, or always |
warps |
"changed", "always" |
"always" |
through a warp: only onto a map of another name, or always |
on_continue |
true or false | true |
when a saved game is continued |
a_hides |
true or false | false |
A takes it away at once |
styles |
table of at most 254 named entries, below | none: none: a plain window | the styles, in order, each named: a picture graphics/ui/banners/<name>.png, else a plain window of the skin |
kinds |
table, below | none: every kind but indoor takes the first style | the style of each kind of map, unless its map.toml says banner |
[world.banner.styles.<name>]
Section titled “[world.banner.styles.<name>]”<a id=“world-banner-styles-name”></a>
One banner style: a picture graphics/ui/banners/<name>.png whose size is the banner’s, else a plain window of the skin. {} is a plain window with the name centred.
Pack record: BANNER_STYLES, a row a style.
| Key | Type | Without it | What it is |
|---|---|---|---|
at |
list of 2: whole number, 0 to 31, then whole number, 0 to 23 | none: [0, 0]: the top left |
where its top-left corner is, in tiles of the screen |
size |
list of 2: whole number, 3 to 32, then whole number, 3 to 8 | none: [12, 4], or the picture’s size |
a plain window’s size in tiles: 3 to 32 across, 3 to 8 down, 40 in all (ignored with a picture) |
text |
list of 2: "centre", "center", "tiles", or whole number, 0 to 255, then whole number, 0 to 255 |
none: centred across, in the middle down | where the name is, [x, y] in pixels inside the banner; x may be “centre” or “tiles” (as wide as the tiles) |
shift |
whole number, -8 to 7 | 0 |
pixels a centred name is moved right (HeartGold centres it two pixels right of the middle); only with text centred |
ink |
list of 2: whole number, 1 to 15, then whole number, 1 to 15 | none: the skin’s | the picture’s colour numbers of the text and of its shadow, 1 to 15 |
picture |
name of a picture of graphics/ui/banners/ without .png | none: the style’s own name | the picture to use |
[world.banner.kinds]
Section titled “[world.banner.kinds]”<a id=“world-banner-kinds”></a>
The banner style of each kind of map: a style of [world.banner.styles], or "none".
Pack record: AREA_BANNERS.
| Key | Type | Without it | What it is |
|---|---|---|---|
town |
name of a style of [world.banner.styles], or “none” | none: the first style | towns |
route |
name of a style of [world.banner.styles], or “none” | none: the first style | routes |
cave |
name of a style of [world.banner.styles], or “none” | none: the first style | caves |
indoor |
name of a style of [world.banner.styles], or “none” | none: none | rooms |
[world.warps]
Section titled “[world.warps]”<a id=“world-warps”></a> Kinds of warps (task 25n): for each, what differs from the engine’s look.
Pack record: WARP_LOOKS, a row a kind, written when a kind is named.
| Key | Type | Without it | What it is |
|---|---|---|---|
door |
table, below | none: the engine’s look for the kind | a door |
mat |
table, below | none: the engine’s look for the kind | a mat at a room’s edge |
stairs |
table, below | none: the engine’s look for the kind | stairs |
walk |
table, below | none: the engine’s look for the kind | walking through an opening |
arrow |
table, below | none: the engine’s look for the kind | an arrow at a map’s edge |
hole |
table, below | none: the engine’s look for the kind | a hole to fall through |
ladder |
table, below | none: the engine’s look for the kind | a ladder |
escalator |
table, below | none: the engine’s look for the kind | an escalator |
panel |
table, below | none: the engine’s look for the kind | a warp panel |
teleport |
table, below | none: the engine’s look for the kind | a teleport |
[world.warps.<kind>]
Section titled “[world.warps.<kind>]”<a id=“world-warps-kind”></a> One kind of warp: only what differs from the engine’s look for it. Ticks are 1/60 s.
Pack record: WARP_LOOKS.
| Key | Type | Without it | What it is |
|---|---|---|---|
fade_out |
whole number, 0 to 255 | none: the engine’s look for the kind | ticks of the fade out; 0 the engine’s usual |
fade_in |
whole number, 0 to 255 | none: the engine’s look for the kind | ticks of the fade in; 0 the engine’s usual |
colour_out |
"black", "white" |
none: the engine’s look for the kind | the colour it fades out to |
colour_in |
"black", "white" |
none: the engine’s look for the kind | the colour it fades in from |
walk_in |
true or false | none: the engine’s look for the kind | the player walks a step into it before the fade |
walk_out |
true or false | none: the engine’s look for the kind | the player walks a step out on arriving |
hide |
true or false | none: the engine’s look for the kind | the player is hidden as it starts |
slow |
true or false | none: the engine’s look for the kind | the steps are slow |
turn_ticks |
whole number, 0 to 255 | none: the engine’s look for the kind | ticks a quarter turn takes while spinning |
turns |
whole number, 0 to 255 | none: the engine’s look for the kind | quarter turns the player spins |
rise |
whole number, -128 to 127 | none: the engine’s look for the kind | sixteenths of a cell the player rises on leaving |
drop |
whole number, -128 to 127 | none: the engine’s look for the kind | sixteenths of a cell above the cell the player arrives from |
lift_ticks |
whole number, 0 to 255 | none: the engine’s look for the kind | ticks the rise and the drop take |
shake |
whole number, 0 to 255 | none: the engine’s look for the kind | how much the screen shakes on arriving |
wait |
whole number, 0 to 255 | none: the engine’s look for the kind | ticks of stillness before the fade |
sound |
name of an effect of audio/audio.txt | none: the engine’s look for the kind | an effect of audio.txt on leaving |
arrive_sound |
name of an effect of audio/audio.txt | none: the engine’s look for the kind | an effect of audio.txt on arriving |
[world.contacts.<name>]
Section titled “[world.contacts.<name>]”<a id=“world-contacts-name”></a>
One kind of furniture cell: pc = { script = "pc", facing = "up" }. A cell of behaviour contact with tag n is the kind n.
Pack record: CONTACTS, a row a kind.
| Key | Type | Without it | What it is |
|---|---|---|---|
script |
name of a script of scripts/common.pfs | must be given | the script of scripts/common.pfs it runs |
facing |
"any", "up", "down", "left", "right", "up_down", "left_right" |
"any" |
the ways the player may face to use it |
[world.followers]
Section titled “[world.followers]”<a id=“world-followers”></a>
Followers (docs/tasks/05h-followers.md): present means on.
Pack record: GAME flags bit GAME_FOLLOWERS.
It has no keys of its own.
[world.field_moves]
Section titled “[world.field_moves]”<a id=“world-field_moves”></a>
Field moves (docs/tasks/05i-field-moves.md): for each, the move or item that does it and the badge it needs.
Pack record: fieldmoves.bin.
| Key | Type | Without it | What it is |
|---|---|---|---|
cut |
table, below | none: CUT |
cutting a small tree |
surf |
table, below | none: SURF |
crossing water |
strength |
table, below | none: STRENGTH |
pushing a boulder |
rocksmash |
table, below | none: ROCKSMASH |
breaking a rock |
waterfall |
table, below | none: WATERFALL |
climbing a waterfall |
rockclimb |
table, below | none: ROCKCLIMB |
climbing a rock wall |
defog |
table, below | none: DEFOG |
clearing fog |
flash |
table, below | none: FLASH |
lighting a dark map |
fly |
table, below | none: FLY |
flying to a town |
dive |
table, below | none: DIVE |
diving under deep water |
[world.field_moves.<move>]
Section titled “[world.field_moves.<move>]”<a id=“world-field_moves-move”></a>
One field move, as an inline table: cut = { move = "CUT", flag = 30 }.
Pack record: fieldmoves.bin.
| Key | Type | Without it | What it is |
|---|---|---|---|
move |
name of a move’s identifier; “” for none | none: the PBS dialect’s own (CUT, SURF…), when the data has it |
the creature’s move that does it |
item |
name of an item’s identifier | none: none | an item in the bag that does it |
flag |
whole number, 0 to 4095 | none: none: always allowed | the saved flag (a badge) without which it cannot be used |
[world.fishing]
Section titled “[world.fishing]”<a id=“world-fishing”></a>
Fishing (task 25v, pl_systems::fishing): a cast, a wait for a bite, a window to press A in, rounds to win, and what is shown. Ticks are 1/60 s. Lists of three are by rod: old, good, super (OldRod, GoodRod, SuperRod tables). Present means on. The player’s sheet while fishing is graphics/sprites.toml’s fish: its four columns are the rod held, the bite, reeling in, the cast.
Pack record: FISHING (48 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
rods |
list of 3: name of an item’s identifier, or “” | none: no item casts: only a script’s fish |
the items that cast each rod when used from the bag (unless the game has an on use hook for one) |
cast |
whole number, 1 to 65535 | 68 |
ticks from the start to the line in the water |
cast_sound |
name of an effect of audio/audio.txt | none: not heard | the cast’s sound |
cast_sound_at |
whole number, 1 to 65535 | 1 |
the tick of the cast it plays on |
wait_base |
whole number, 0 to 65535 | 60 |
a wait for a bite is wait_base + wait_step * min(r + first, wait_cap) ticks, r drawn below wait_count |
wait_step |
whole number, 0 to 65535 | 60 |
see wait_base; with dots, a dot each step |
wait_count |
whole number, 1 to 65535 | 4 |
see wait_base |
wait_cap |
whole number, 0 to 65535 | 65535 |
see wait_base |
wait_first |
whole number, 0 to 255 | 0 |
added to the draw in the first round |
no_bite |
whole number, 0 to 65535 | 240 |
ticks a cast nothing will bite waits; 0: a wait drawn as for a bite |
windows |
list of 3: whole number, 0 to 65535 | none: 90, 60, 30 | ticks to press A in after a bite, by rod |
reel |
whole number, 0 to 65535 | 30 |
ticks from the press in time to the creature landed |
bite |
whole number, 0 to 100 | 0 |
percent chance of a bite; 0: the rod’s table’s rate |
sticky |
true or false | true |
the lead’s Suction Cups or Sticky Hold doubles the chance of a bite |
rounds |
list of 3: whole number, 1 to 255 | none: 1, 1, 1 | rounds a cast must win, by rod, at the least |
spread |
list of 3: whole number, 1 to 255 | none: 1, 1, 1 | a draw below this is added to rounds |
more |
list of 3: whole number, 0 to 100 | none: 0, 0, 0 | percent chance of one more round after the first, by rod |
early |
"own", "miss" |
"own" |
A before a bite: its own message (reeled in too soon), or as nothing biting in the first round and the creature getting away after |
dots |
true or false | false |
the wait shows a dot (fish_dot) in the box every wait_step ticks |
bite_text |
true or false | false |
a bite says so in the box (fish_bite) |
bite_emote |
true or false | true |
a bite shows the alert emote above the player |
landed_press |
true or false | true |
the landed message (fish_landed) waits for a button before the battle; false: the battle starts once it is typed out |
[light]
Section titled “[light]”<a id=“light”></a>
Light and outlines. The light tables themselves are lights.toml.
Pack record: each map’s header.
| Key | Type | Without it | What it is |
|---|---|---|---|
edges |
list of 1 to 8 colours "#rrggbb", or false |
none: no outlines | the outline colours of every map that does not say its own: polygon IDs 0-7, 8-15 and so on; a shorter list repeats its last |
edges_rear |
whole number, 0 to 63 | 0 |
the polygon ID of the rear plane, so that an opaque polygon is outlined against what is behind a room |
[text]
Section titled “[text]”<a id=“text”></a> Text.
Pack record: none: the build.
| Key | Type | Without it | What it is |
|---|---|---|---|
wide_text |
"error", "cut" |
"error" |
a line too wide for its box: an error, or a note and the box cuts it (for text written for other windows, as an import’s is) |
[rules]
Section titled “[rules]”<a id=“rules”></a>
Rules a new game starts with (task 11i); a script reads and changes them (rule, setrule).
Pack record: GAME (level_cap, rules; lose_money is a bit of flags).
| Key | Type | Without it | What it is |
|---|---|---|---|
lose_money |
"none", "by_badges" |
"none" |
losing a battle takes money (today by the strongest creature’s level, as with no badge) |
level_cap |
whole number, 0 to 100 | 0 |
no creature trains past it, and none above it can be caught; 0 for none |
exp_all |
true or false | false |
experience to the whole party |
no_battle_items |
true or false | false |
only capsules from the bag in a battle |
battle_style |
"shift", "set" |
"shift" |
whether the player may switch when the foe sends out its next creature |
daycare |
"modern", "emerald", "platinum", "heartgold", "black2" |
"modern" |
the day care’s rules, one game’s (task 25t) |
wild |
"modern", "emerald", "platinum", "heartgold", "black2" |
"modern" |
the rules of wild encounters, one game’s: what the lead creature’s ability, held item and charms do to the roll, and how roamers move (task 25z) |
bag |
"modern", "emerald", "platinum", "heartgold", "black2" |
"modern" |
the bag’s rules, one game’s: slots by pocket, stack sizes, how many items are registered, the free space (task 11m) |
tera |
true or false | false |
the player’s creatures may terastallize, one a battle, into their tera type (task 36a) |
zmove |
true or false | false |
the player’s creatures may use a Z-move, one a battle, through a held Z-crystal (task 36b) |
challenge |
table, below | none: not offered | the challenge mode (permadeath, decision 104) |
currencies |
table of at most 8 named entries, below | none: money alone | the game’s currencies beside money, numbered in the order written from 0 (task 30i) |
keep_field_moves |
true or false | false |
a creature cannot forget a field move to learn another, in the level-up, evolution and tutor screens: only the move deleter removes it, as Emerald, Platinum and HeartGold have it (task 11l) |
tutors |
table of at most 32 named entries, below | none: no tutors | the move tutors, numbered in the order written from 0: each its moves and their prices (task 11l) |
[rules.challenge]
Section titled “[rules.challenge]”<a id=“rules-challenge”></a>
The challenge mode (decision 104, docs/tasks/11c-challenge-mode.md). Its rules are kept whether the title screen offers it or a script turns it on (setrule challenge, 1).
Pack record: GAME (flags bits GAME_CHALLENGE, GAME_CHALLENGE_FIRST, GAME_CHALLENGE_SCRIPT; challenge_box).
| Key | Type | Without it | What it is |
|---|---|---|---|
on |
true or false | false |
the title screen offers it on a new game |
first |
true or false | false |
only the first creature met in an area may be caught |
lost |
"box", "release" |
"box" |
what becomes of a creature it takes |
over |
"title", "script" |
"title" |
nothing left that can fight: the game ends, or the shared script’s on gameover runs |
box |
whole number, 1 to 20 | 18 |
the box it keeps the creatures it takes in; not with lost = "release" |
[rules.currencies.<name>]
Section titled “[rules.currencies.<name>]”<a id=“rules-currencies-name”></a>
One of the game’s currencies beside money (coins, points), named for scripts (givecurrency coins, 10): coins = { label = "cur_coins", max = 9999 }. Saved with the game (save section 19).
Pack record: CURRENCIES, a row a currency (8 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
label |
name of a line of text.txt | must be given | its name on screen, beside the amount |
max |
whole number, 1 to 999999999 | 9999 |
the most the player may hold |
[rules.tutors.<name>]
Section titled “[rules.tutors.<name>]”<a id=“rules-tutors-name”></a>
One move tutor, named for scripts (teach cove, slot). Which creature may be taught a move is its species’ TutorMoves.
Pack record: TUTORS, a row a move (8 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
moves |
table of at most 64 named entries, below | none: none | the moves it teaches, in the order written |
[rules.tutors.<name>.moves.<move>]
Section titled “[rules.tutors.<name>.moves.<move>]”<a id=“rules-tutors-name-moves-move”></a>
One move of a tutor, named by its identifier: BRACE = { cost = 3, pay = "coins" }.
Pack record: TUTORS.
| Key | Type | Without it | What it is |
|---|---|---|---|
cost |
whole number, 0 to 65535 | 0 |
how much; 0 teaches for nothing |
pay |
name of money, a currency of [rules.currencies] or an item’s identifier |
"money" |
what it is paid in |
[hall]
Section titled “[hall]”<a id=“hall”></a>
The Hall of Fame (task 11k, docs/creating-a-game.md, “The end”).
Pack record: GAME (hall_limit).
| Key | Type | Without it | What it is |
|---|---|---|---|
limit |
whole number, 0 to 50 | 0 |
the most teams it keeps, the oldest going first; 0 for as many as the save holds |
[time]
Section titled “[time]”<a id=“time”></a> The clock (task 11f). Runs of saved flags and variables start again when a day begins, or a week (on Sunday).
Pack record: TIME (20 bytes), written when the table is there.
| Key | Type | Without it | What it is |
|---|---|---|---|
daily_flags |
[first, last], 0 to 4095 |
none: none | saved flags cleared when a day begins |
daily_vars |
[first, last], 0 to 511 |
none: none | saved variables set to 0 when a day begins |
weekly_flags |
[first, last], 0 to 4095 |
none: none | saved flags cleared when a week begins |
weekly_vars |
[first, last], 0 to 511 |
none: none | saved variables set to 0 when a week begins |
clock_changed |
"penalty", "ignore" |
"penalty" |
a clock turned back: new days held back for penalty_hours, or every change of date a new day |
penalty_hours |
whole number, 0 to 8760 | 24 |
hours a clock turned back holds new days back for |
resync_minutes |
whole number, 0 to 255 | 1 |
minutes between the game’s looks at the platform’s clock; 0 never |
[battle]
Section titled “[battle]”<a id=“battle”></a> The battle’s presentation and sound (task 13e).
Pack record: SOUNDS (40 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
low_hp |
"none", "alarm", "music" |
"none" |
the player’s creature in danger: nothing, the alarm effect again and again, or the danger track over the battle’s |
surf_scene |
name of a battle scene | none: the map’s scene | the scene of a battle begun while surfing, on any map |
music |
table, below | none: no battle music | the battle’s tracks |
sounds |
table, below | none: no battle sounds | the battle’s effects and the menus’ refusal |
[battle.music]
Section titled “[battle.music]”<a id=“battle-music”></a>
The battle’s tracks, by their names in audio/audio.txt.
Pack record: SOUNDS music.
| Key | Type | Without it | What it is |
|---|---|---|---|
wild |
name of a track of audio/audio.txt | none: not heard | a wild battle |
trainer |
name of a track of audio/audio.txt | none: not heard | a trainer’s battle |
rival |
name of a track of audio/audio.txt | none: not heard | a trainerbattle ... called: rival |
final |
name of a track of audio/audio.txt | none: not heard | a trainerbattle ... music: final |
victory |
name of a track of audio/audio.txt | none: not heard | in the battle’s place once it is won; a once track is a fanfare |
danger |
name of a track of audio/audio.txt | none: not heard | over the battle’s while the player’s creature is in danger (low_hp = "music") |
last |
name of a track of audio/audio.txt | none: not heard | in the battle’s place as a leader’s last creature comes out ([audio.music] leaders; task 25u) |
[battle.sounds]
Section titled “[battle.sounds]”<a id=“battle-sounds”></a>
The battle’s effects and the menus’ refusal, by their names in audio/audio.txt.
Pack record: SOUNDS sfx.
| Key | Type | Without it | What it is |
|---|---|---|---|
hit |
name of an effect of audio/audio.txt | none: not heard | a move’s hit |
hit_strong |
name of an effect of audio/audio.txt | none: not heard | a super effective hit |
hit_weak |
name of an effect of audio/audio.txt | none: not heard | a hit that is not very effective |
stat_up |
name of an effect of audio/audio.txt | none: not heard | a stat rises |
stat_down |
name of an effect of audio/audio.txt | none: not heard | a stat falls |
status |
name of an effect of audio/audio.txt | none: not heard | a creature is given a status |
shake |
name of an effect of audio/audio.txt | none: not heard | a capsule rocks; it shuts for good |
catch |
name of an effect of audio/audio.txt | none: not heard | a creature is caught |
alarm |
name of an effect of audio/audio.txt | none: not heard | the low-HP alarm (low_hp = "alarm"), again as it ends |
exp |
name of an effect of audio/audio.txt | none: not heard | the experience bar filling |
refuse |
name of an effect of audio/audio.txt | none: not heard | something asked for cannot be done, in any menu |
<a id=“ui”></a> Menus and screens.
| Key | Type | Without it | What it is |
|---|---|---|---|
bottom |
table, below | none: the skin’s picture alone; no BOTTOM record |
the field’s touch screen (task 11h) |
options |
table of at most 16 named entries, below | none: the engine’s rows only | the game’s own rows of the options screen, after the engine’s, in the order written (task 11i) |
[ui.bottom]
Section titled “[ui.bottom]”<a id=“ui-bottom”></a> The field’s touch screen (task 11h): the skin’s picture with parts placed on it. Rectangles are tiles of 8 pixels on the 32 × 24 tiles of the screen.
Pack record: BOTTOM (44 bytes), written when the table is there.
| Key | Type | Without it | What it is |
|---|---|---|---|
style |
"picture", "menu", "apps" |
"picture" |
the picture alone, the menu as touch buttons, or small apps |
columns |
whole number, 1 to 4 | 2 |
style menu: the buttons’ columns |
menu |
[x, y, width, height] in tiles, inside 32 × 24 |
[1, 0, 30, 20] |
style menu: where the buttons go |
context |
[x, y, width, height] in tiles, inside 32 × 24 |
none: no such button | style menu: a button that does what A does |
yes_no |
true or false | false |
style menu: a yes-or-no question is also two buttons |
apps |
list of 1 to 8: "clock", "party", "steps" |
["clock", "party", "steps"] |
style apps: the apps, in the order they turn |
screen |
[x, y, width, height] in tiles, inside 32 × 24 |
[2, 2, 26, 20] |
style apps: where an app draws |
next |
[x, y, width, height] in tiles, inside 32 × 24 |
[28, 2, 4, 20] |
style apps: touching here shows the next app (R does too) |
app_flag |
whole number, 0 to 4095 | none: every app is there | style apps: app n is there once this flag plus n is set |
ink |
list of 2: whole number, 1 to 15 | none: the skin’s ink and shade | style apps: two colours of the picture’s palette the apps draw in, ink and a lighter one |
nav |
[x, y, width, height] in tiles, inside 32 × 24 |
none: no map page | style menu: where the map page goes (the region map of graphics/ui/bottom/map.png with the player’s square marked); the buttons then show only while the menu is open, in its place (task 24d) |
party |
[x, y, width, height] in tiles, inside 32 × 24 |
none: no party | style menu: where the party at a glance goes, a level and a bar of health a member |
open |
[x, y, width, height] in tiles, inside 32 × 24 |
none: no such button | style menu: a button that opens the menu, and closes it while open |
[ui.options.<name>]
Section titled “[ui.options.<name>]”<a id=“ui-options-name”></a>
One of the game’s own options, named for scripts (getoption, on option): max_evs = { label = "opt_max_evs", about = "opt_max_evs_about" }. Its words are lines of text.txt.
Pack record: OPTIONS, a row an option (16 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
label |
name of a line of text.txt | must be given | the row’s name |
about |
name of a line of text.txt | must be given | what the row is about, shown below the table |
values |
list of 2 to 4: name of a line of text.txt | ["opt_off", "opt_on"] |
the names of its values, from 0 |
default |
whole number, 0 to 3 | 0 |
the value a new game has: the number of one of values |
[audio]
Section titled “[audio]”<a id=“audio”></a> The interface’s sounds, how the music goes down under cries and fanfares, and the stereo-or-mono option (task 25k).
Pack record: AUDIO, written when the table is there.
| Key | Type | Without it | What it is |
|---|---|---|---|
sound_option |
true or false | false |
the options screen offers stereo or mono |
mono |
true or false | false |
a new game’s choice is mono; needs sound_option = true |
save_sound |
"write", "message" |
"write" |
the save’s sound: as the save succeeds, or once the message after it is typed out |
warp_doors |
true or false | true |
a warp through a door plays the door’s sounds |
mono_copies |
true or false | true |
the DS plays mono music from mono copies of the tracks |
cry_level |
whole number, 0 to 256 | 256 |
the music under a cry, out of 256 (256: untouched) |
cry_down |
whole number, 0 to 255 | 0 |
ticks the music takes to go down under a cry |
cry_up |
whole number, 0 to 255 | 0 |
ticks it takes to come back up after the cry |
fanfare_out |
whole number, 0 to 255 | 0 |
ticks the music fades out before a fanfare |
fanfare_in |
whole number, 0 to 255 | 0 |
ticks it fades in after it |
fanfare_gap |
whole number, 0 to 255 | 0 |
ticks it stays quiet between the two |
sounds |
table, below | none: the engine’s own sounds, by their places in audio.txt | the interface’s sounds, by event |
screens |
table, below | none: every screen the general sounds | screens’ own sounds (task 25m) |
doors |
table of at most 7 named entries, below | none: none: doors make the general sounds | door sounds a piece names by door_sound, in order from 1 (task 25m) |
music |
table, below | none: no rules, each map plays its music |
which track plays: by the hour, the season, surfing or cycling, a variable, a flag; trainers’ eyes (task 25u) |
[audio.sounds]
Section titled “[audio.sounds]”<a id=“audio-sounds”></a>
The interface’s sounds, by event, by their names in audio/audio.txt. With this table every event it does not name is silent.
Pack record: AUDIO ui.
| Key | Type | Without it | What it is |
|---|---|---|---|
cursor |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
the cursor moves |
select |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a choice is made |
cancel |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a menu is left |
menu_open |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a menu opens |
menu_close |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a menu closes |
text_next |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a message turns a page |
text_end |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a message ends |
bump |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
the player walks into something |
door_open |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a door opens |
door_close |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a door closes |
ledge |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a hop down a ledge |
land |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
the landing |
splash |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
into water |
step_snow |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a step in snow |
step_puddle |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a step in a puddle |
step_shallows |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a step in shallow water |
step_mud |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a step in mud |
step_grass |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a step in tall grass |
save |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
the game is saved |
warp |
name of an effect of audio/audio.txt | none: silent (when [audio.sounds] is there) |
a warp |
[audio.screens]
Section titled “[audio.screens]”<a id=“audio-screens”></a> Screens with sounds of their own (task 25m), each a table.
Pack record: SCREEN_SOUNDS, a row a screen.
| Key | Type | Without it | What it is |
|---|---|---|---|
menu |
table, below | none: the general sounds | the field menu |
bag |
table, below | none: the general sounds | the bag |
party |
table, below | none: the general sounds | the party |
summary |
table, below | none: the general sounds | a creature’s summary |
storage |
table, below | none: the general sounds | the storage boxes |
dex |
table, below | none: the general sounds | the dex |
shop |
table, below | none: the general sounds | a shop |
options |
table, below | none: the general sounds | the options |
battle |
table, below | none: the general sounds | the battle’s menus |
[audio.screens.<screen>]
Section titled “[audio.screens.<screen>]”<a id=“audio-screens-screen”></a>
One screen’s own sounds, by their names in audio/audio.txt; "" is silent there.
Pack record: SCREEN_SOUNDS.
| Key | Type | Without it | What it is |
|---|---|---|---|
cursor |
name of an effect of audio/audio.txt, or a list of 1 to 3 | none: the general sound; "" for none |
the cursor moves; with a list, each move plays the next |
select |
name of an effect of audio/audio.txt | none: the general sound; "" for none |
a choice is made |
cancel |
name of an effect of audio/audio.txt | none: the general sound; "" for none |
the screen is left |
page |
name of an effect of audio/audio.txt | none: the general sound; "" for none |
a page turns |
[audio.doors.<name>]
Section titled “[audio.doors.<name>]”<a id=“audio-doors-name”></a>
A door sound, named for pieces’ door_sound: sliding = { open = "slide" }.
Pack record: DOOR_SOUNDS, a row a door sound.
| Key | Type | Without it | What it is |
|---|---|---|---|
open |
name of an effect of audio/audio.txt | none: none | the door opens |
close |
name of an effect of audio/audio.txt | none: none | the door closes |
[audio.music]
Section titled “[audio.music]”<a id=“audio-music”></a>
The music rules (task 25u, crate::music_rules): which track plays on a map. The rules of order are tried first to last; the first that gives a track plays, else the map’s own: its season’s (music_seasons), its night track at night (music_night), its music. A map’s map.toml gives its own tracks.
Pack record: MUSIC_RULES, MUSIC_EYES, MUSIC_ALT; the maps’ AREA_MUSIC.
| Key | Type | Without it | What it is |
|---|---|---|---|
order |
list of 0 to 4: "override", "flag", "surf", "bike" |
none: the map’s own track | the rules before the map’s own, first first: override (the variable holds a track), flag (the map’s music_flag is set), surf, bike |
night |
true or false | false |
a map’s music_night plays while the clock says night |
season_var |
whole number, 0 to 511 | none: no seasons | the variable that holds the season, 0 to 3: a map’s music_seasons by it |
surf |
name of a track of audio/audio.txt | none: the map’s own | the track while surfing, on a map whose travel_music is not false |
bike |
name of a track of audio/audio.txt | none: the map’s own | the track while cycling, the same |
override_var |
whole number, 0 to 511 | none: no override | the variable musicoverride keeps its track in (the track plus one; 0 none) |
alt_flag |
whole number, 0 to 4095 | none: no alternative set | while this flag is set, each track of alt plays its alternative, the battle’s too |
alt |
a table of track = "its alternative", tracks of audio.txt |
none: no arrangements | the alternative set’s arrangements |
eyes_default |
name of a track of audio/audio.txt | none: nothing changes | the track eyemusic plays for a class eyes does not name |
eyes |
a table of CLASS = "track", or CLASS = ["track", "track"] by the map’s music_region |
none: every class eyes_default |
trainer classes’ tracks for eyemusic |
leaders |
list of 0 to 256: name of a trainer class | none: no leaders | classes whose last creature brings [battle.music] last |
[content]
Section titled “[content]”<a id=“content”></a>
The content source (plan 40): its maps’ gameplay, scripts, text and data, and every number. ploom restyle lays its maps down in the project’s style.
| Key | Type | Without it | What it is |
|---|---|---|---|
source |
name of a source of sources.toml | none: none: an original game | the source the story comes from |
[style]
Section titled “[style]”<a id=“style”></a>
Where each family’s look comes from (plan 40): a chain of sources a family, tried in order after the project’s own art (art/artset.toml); a role none draws is the content source’s own, lifted into the project’s style, else the engine’s. Resolved by ploom build; the pack does not know of sources.
| Key | Type | Without it | What it is |
|---|---|---|---|
world |
name of a source of sources.toml, or a list of 1 to 16 | none: the project’s own art alone | ground, pieces, buildings, edges: the first source is the anchor, whose camera, light and edge rules the maps take |
order |
table, below | none: chain-major | how each family’s chain is walked |
pick |
table of at most 1024 named entries, each name of a source of sources.toml | none: no pins | single roles (and the roles under them) pinned to one source, like "building.lab" = "black"; the content source’s name keeps its own art, lifted |
[style.order]
Section titled “[style.order]”<a id=“style-order”></a> How a family’s chain is walked.
| Key | Type | Without it | What it is |
|---|---|---|---|
world |
"chain", "role" |
"chain" |
chain: every fallback of a source before any of the next; role: a role’s exact art in any source before a parent role’s |
[graphics]
Section titled “[graphics]”<a id=“graphics”></a>
The game’s look decisions (plan 42 2.4, decision 315): the presentation preset a new player starts at and the most a player may choose. They change only how the game is drawn, never the game. The rows and their choices are pl-present’s (docs/plans/42-presentation-and-modern-graphics.md, 2.3).
Pack record: GRAPHICS (36 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
default |
"auto", "classic", "high", "ultra" |
none: auto: the best the player’s machine holds |
the preset a new player starts at; classic is the DS’s picture |
modern |
true or false | true |
false: only classic; a player may change only the upscaler and the accessibility rows |
cap |
table of at most 32 named entries, each text | none: no caps | the most a player may choose of a row, like { bloom = "low", shadows = "map-2048" }; never an accessibility row |
[coop]
Section titled “[coop]”<a id=“coop”></a>
Several players in one field (docs/plans/43-coop.md 8.1, task 33c). Present means on. On one machine each local pad is a player: a second pad’s START joins. Warps take everyone; the Start menu and the field moves are the first player’s.
Pack record: COOP (12 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
mode |
"field", "off" |
"field" |
field: players share one field; off: one player |
max_players |
whole number, 1 to 8 | 2 |
players at most |
couch |
true or false | true |
several local pads on one desktop |
leash |
whole number, 0 to 255 | 12 |
cells a player may go from the players’ middle; 0 none |
camera |
"leash", "zoom" |
"leash" |
one view on the players’ middle; zoom also pulls back to fit them |
zoom_max |
whole number, 0 to 32 | 6 |
cells of distance the zoom may add |
crowd |
table, below | its keys’ defaults | the crowd rules |
[coop.crowd]
Section titled “[coop.crowd]”<a id=“coop-crowd”></a>
The crowd rules (docs/plans/43-coop.md 4.4): from at players in view.
Pack record: COOP.
| Key | Type | Without it | What it is |
|---|---|---|---|
at |
whole number, 2 to 8 | 5 |
players in view from which the crowd rules apply |
others |
"solid", "ghost", "hidden" |
"ghost" |
how the other players look in a crowd |
ghost_alpha |
whole number, 0 to 31 | 12 |
a ghost’s opacity, 0 to 31 |
collide |
"on", "off", "auto" |
"auto" |
whether players block each other; auto: not in a crowd |
names |
"none", "near", "all" |
"near" |
name tags over players |
followers |
"all", "own", "none" |
"own" |
whose followers are drawn in a crowd |
[limits]
Section titled “[limits]”<a id=“limits”></a>
What the game may use at run time (docs/plans/48-targets-and-limits.md, decision 341). Each is a limit of the machine it runs on: a game that targets the DS gets the DS’s numbers on every platform and may not ask for more (the build says so); a desktop-only game gets the desktop’s and may ask for more state. The resources (textures to sprites) are the platform’s when left out and may only be lowered; the state (boxes to vars) shapes the save, so it is the game’s, the same on every platform. Do not change the state once players have saves.
Pack record: LIMITS (48 bytes), with [game] targets.
| Key | Type | Without it | What it is |
|---|---|---|---|
texture_bytes |
whole number, 1 to 524288 | none: the platform’s (the DS’s while the DS is a target) | bytes of texture memory a map’s textures and the characters’ sheets take together (the DS: 262,144) |
texture_colors |
whole number, 1 to 32768 | none: the platform’s (the DS’s while the DS is a target) | texture palette colours they take (the DS: 4,096) |
textures |
whole number, 1 to 4096 | none: the platform’s (the DS’s while the DS is a target) | textures held at once (the DS: 256) |
meshes |
whole number, 1 to 16384 | none: the platform’s (the DS’s while the DS is a target) | mesh instances the field lists in a frame: ground blocks, pieces, characters, shadows (the DS: 256) |
polygons |
whole number, 1 to 1048576 | none: the platform’s (the DS’s while the DS is a target) | polygons a frame draws (the DS: 2,048) |
sprites |
whole number, 1 to 1024 | none: the platform’s (the DS’s while the DS is a target) | sprites a screen shows (the DS: 128) |
stream_bytes |
whole number, 1 to 16777216 | none: the platform’s (the DS’s while the DS is a target) | bytes of a map read in a tick while walking (the DS: 16,384) |
boxes |
whole number, 1 to 255 | 18 |
storage boxes (the DS: at most 20) |
save_bytes |
whole number, 1 to 67108864 | 262144 |
bytes one copy of a save may take; its largest must fit (the DS: at most 262,144) |
flags |
whole number, 1 to 16384 | 4096 |
saved script flags (the DS: at most 4,096) |
vars |
whole number, 1 to 16384 | 512 |
saved script variables (the DS: at most 512) |
[camera]
Section titled “[camera]”<a id=“camera”></a>
The field’s cameras (task 28g): presets a map names by its camera. A map that names none has the first; a game with none has the engine’s own (60° down, 40 cells back, a 17° field of view). A camera zone of a map (an events object of class camera) frames with the same keys and units.
| Key | Type | Without it | What it is |
|---|---|---|---|
presets |
table of at most 254 named entries, below | none: none: the engine’s own camera | the presets, numbered in the order written from 0; a map’s camera names one |
[camera.presets.<name>]
Section titled “[camera.presets.<name>]”<a id=“camera-presets-name”></a> A camera preset: it looks at the followed character from the south, tilted down, with no turn. Fractions keep an imported camera to the bit.
Pack record: CAMERAS, a row a preset (32 bytes).
| Key | Type | Without it | What it is |
|---|---|---|---|
pitch |
number, 1 to 89 | must be given | its tilt down from level, in degrees |
distance |
number, 16 to 32000 | must be given | from the point it looks at back to the eye, in sixteenths of a cell |
fov |
number, 0.5 to 150 | must be given | its field of view top to bottom, in degrees; an orthographic camera shows at every depth what this shows at distance |
projection |
"perspective", "orthographic" |
"perspective" |
perspective, or orthographic: every cell of ground the same size however far |
near |
number, 1 to 32000 | none: a quarter of distance |
the near plane, from the eye, in sixteenths of a cell: nearer is not drawn |
far |
number, 1 to 64000 | none: twice distance |
the far plane, from the eye, in sixteenths of a cell: further is not drawn |
offset_x |
number, -12 to 12 | none: 0 | where it looks from the followed character: east, in cells |
offset_y |
number, -12 to 12 | none: 0 | where it looks from the followed character: south, in cells |
offset_up |
number, -12 to 12 | none: 0 | where it looks from the followed character: up, in cells |