Game settings
game.toml sits at the top of the project folder. It is the game’s profile: every
way this game differs from another PokeLoom game that is not content (maps, text,
scripts, pictures) is a key here. The engine never asks which game it is running; it
reads these keys. Two games on the same engine can differ only in their game.toml
and still play and look different. See One model for why.
This page explains how the file is organised. The full list of keys, with types, ranges and defaults, is the game.toml reference, generated from the engine’s own declarations so it is never out of date.
Defaults
Section titled “Defaults”Every group and every key may be left out. A key left out takes its default, and a group left out leaves the engine as it is without it: no banner, no followers, no fishing, no co-op. That is why the sample’s file is short and still makes a whole game. Add a key when you want something other than the default, not before.
Groups
Section titled “Groups”| Group | What it holds | Page |
|---|---|---|
[game] |
The title, the game’s id (the folder its saves live in), the list of maps, the start map, the data source | this page |
[world] |
The field: character cards, the shadow, the location banner, warp looks, furniture cells, followers, field moves, fishing | Characters, The joined world, Map settings |
[light] |
Outlines where pieces meet, for every map that does not set its own | Light and weather |
[text] |
What to do with a line too wide for its box | Text |
[rules] |
Rules a new game starts with: level cap, experience to the party, the challenge mode, currencies, move tutors, one game’s day care, wild or bag rules | Battle rules, Rules, options and cheats |
[hall] |
How many teams the Hall of Fame keeps | Game systems |
[time] |
Flags and variables that reset each day or week; what a clock turned back does | Game systems |
[battle] |
The battle’s music, sounds and surf scene | Battles, Audio |
[ui] |
The touch screen in the field and the game’s own options | Gadgets, Menus |
[audio] |
Interface sounds, music rules, the stereo or mono option | Audio |
[content], [style] |
Where the story and the look come from, for a game built from other sources | Assets and style chains |
[graphics] |
The presentation preset a new player starts at, and caps on what a player may choose | Presentation settings |
[coop] |
Several players in one field | Co-op |
The groups split the file by who cares about it. A designer tuning the battle’s sound
works in [battle] and [audio]; nobody needs to read the whole file to change one
thing.
Example
Section titled “Example”These lines are from the sample’s game.toml, with its comments shortened.
[game]title = "PokeLoom sample game"# Map folders under maps/, in the order warps and scripts number them.maps = ["home", "town", "lab", "parlour", "garden", "hill", "weir"]# The map a new game starts on.start = "home"
# The day care keeps HeartGold's rules.[rules]daycare = "heartgold"# A field move is kept until the move deleter takes it.keep_field_moves = true
[battle]low_hp = "alarm"
# Field moves: the sample's own moves do them, once the weir keeper's# permit (flag 10) is given.[world.field_moves]cut = { move = "GUSTCUT", flag = 10 }surf = { move = "UNDERTOW", flag = 10 }
# Kinds of warps: what differs from the engine's look.[world.warps.panel]sound = "whistle"arrive_sound = "hop"What each part does:
mapsis the list of map folders. Without it, every folder ofmaps/that holds amap.tmjis a map, in alphabetical order. Maps are known by name everywhere you write them, so reordering the list does not break warps, scripts or old saves.startis the map a new game begins on, at itsstartevent.daycare = "heartgold"picks one game’s day care rules instead of the modern ones. Rules like this are named by the game they come from because that is the clearest way to describe a set of numbers; the engine has one day care and these are its settings.[world.field_moves]says which move does each field action and which flag (a badge) allows it. The sample’s moves are its own.[world.warps.panel]changes only the sounds of one kind of warp and keeps the engine’s look for the rest.
[game] id is worth setting early. It names the folder the game’s saves are kept in,
apart from every other game’s. Without it the project folder’s name is used. Do not
change it once players have saves.
Errors
Section titled “Errors”ploom check reads every settings file and reports every mistake at once, each with
its file and line, before anything is converted. The same checks run in ploom build.
The messages say what was expected and, for a misspelt key, what was meant:
game.toml:1: `rulez` is not a setting of game.toml; did you mean `rules`? (game.toml has: game, world, light, text, rules, hall, time, battle, ui, audio, content, style, graphics, coop, limits)game.toml:3: [rules] `level_cap` must be a whole number from 0 to 100; it is 101game.toml:8: [time] `dayly_flags` is not a setting of [time]; did you mean `daily_flags`? ([time] has: daily_flags, daily_vars, weekly_flags, weekly_vars, clock_changed, penalty_hours, resync_minutes)An unknown key is an error, not a warning, on purpose. A typo that is silently ignored is a setting you think you made and did not.
ploom schema --markdown prints the reference from the declarations; ploom schema map, world and lights print the references of the other settings files.
Debug start
Section titled “Debug start”test_start = true in [game], with a map named teststart, makes a new game chosen
with SELECT held start on that map instead of the start map. Give it a script whose
on enter hands the player what the earlier part of the game would have (creatures,
items, flags) and warps to where you are working. Take the line out before you
release the game.
Imports
Section titled “Imports”An imported game is a project like any other, and its differences from the engine’s
defaults are written into its game.toml by the importer: its warp looks, its
banner timing, its sound tables. You can open it, read it and change it. No engine
code knows which game was imported. See Importing games.
Planned
Section titled “Planned”Planned (plan 25): more of what separates the handheld games becomes keys of this
file: a [camera] group with a table of presets and camera areas, a [save] group
for box and pocket layout, named fonts and frames in [text], battle layout and
transitions in [battle], and a [features] list for features with no settings of
their own. Each is added to the declarations, so it appears in the reference and is
checked like the keys above. Planned (plan 25): ploom new takes a style
(gba, gen4, gen5) and writes a starting game.toml for it.