Skip to content

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.

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.

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.

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:

  • maps is the list of map folders. Without it, every folder of maps/ that holds a map.tmj is 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.
  • start is the map a new game begins on, at its start event.
  • 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.

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 101
game.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.

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.

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