Skip to content

One model

The engine never asks which game it is running. There is no game = "platinum" key, and no engine code branches on a game’s name. Every difference between two games is exactly one of four kinds (plan 25, decision 204):

Kind What it is Where it lives Example
Setting A value the engine reads A key of game.toml, or of a map’s map.toml The day care’s rules, a character’s card size
Feature Engine code every runtime carries, on when the game turns it on A table of game.toml; present means on Followers, fishing, the location banner
Content The game’s own data and assets The project’s folders Maps, scripts, text, trainers, encounters, art
Import Knowledge of a source format The importer only, never the engine How one game packs its maps or encodes its text

A reference game, such as an imported Platinum, is a set of settings plus content that the importer writes into a project folder. A new game is the same thing written by hand. The engine cannot tell them apart, and does not need to.

Five games on one engine. The owner asked for “a single model that will support all of these games, including emerald”, whose differences are “simply settings changes” (decision 204). Reading Emerald, Platinum, HeartGold, Black and Black 2 side by side showed they differ far less in kind than in presentation: the large systems are shared, and most differences are numbers, tables and looks (plan 25, section 1).

Mixing is free. When a difference is a setting, any game can take it. A new game can use HeartGold’s day care rules with Black’s character proportions and its own lower screen. If the difference were a branch on a game’s name, nobody could mix.

One data set. Species, moves, abilities, items, types and natures come from one modern set shared by every game (Showdown’s, decisions 71 and 204). A game chooses which of them it uses and in what order, never their numbers. An older region can therefore include creatures from any later generation.

Smaller code. A feature written once serves every game that turns it on. The DS has 4 MB of RAM; five copies of a system would not fit.

A test of every feature. Before something enters the engine, it must be described so that a new game would want it. The game-specific part (one gym’s machinery, one game’s numbers) is content on a general feature (plan 25, P9; decision 158’s gate).

game.toml is the game’s profile. Every key is declared once, with its type, range and default, and the reference is generated from those declarations (game.toml: every key). A key that is not declared is an error, and ploom check reports every mistake in the file at once, each with its line.

The keys are in groups. A group left out is the engine’s defaults.

Group What it holds
[game] Identity: id, title, the list of maps, where a new game starts
[world] The field: character cards, shadows, banner, warps, furniture cells, followers, field moves, fishing
[light] Outline colours; the light tables themselves are lights.toml
[text] How text that is too wide is treated
[rules] Rules a new game starts with: day care, wild roll, bag, level cap, tutors, currencies, challenge mode
[hall] The Hall of Fame
[time] Daily and weekly resets, the clock’s rules
[battle] The battle’s presentation, music and sounds
[ui] The lower screen, the game’s own option rows
[audio] Interface sounds, the music’s rules
[content], [style] Where the story and the look come from (plan 40)
[graphics] The presentation preset a new player starts at, and caps
[coop] Several players in one field

Planned (plan 25): groups for the camera presets and areas, the save’s shape (boxes, pockets) and a list of switched-on features with no settings of their own.

The sample game keeps HeartGold’s day care rules. It says so in one line of its game.toml:

# The day care keeps HeartGold's rules: an egg cycle of 255 steps, Power
# items and the Everstone from either parent (docs/creating-a-game.md).
[rules]
daycare = "heartgold"

The value is a named set of rules, read from that game’s decompilation and built into the engine once. Any game may choose it; the engine does not know or care which game the name came from. The same holds for the wild roll (wild) and the bag (bag), each with modern as the default.

Here are two field settings of a game whose people are drawn as camera-facing cards with the DS’s anti-aliasing, as generation 4 draws them, beside a game that keeps the defaults:

# A game in the manner of generation 4
[world]
character_facing = true
antialias = true
[rules]
daycare = "platinum"
wild = "platinum"
bag = "platinum"
# A new game with modern rules: no [world] keys, so cards stand upright
[rules]
daycare = "modern"

Both run on the same engine binary. Nothing else changes: the same maps would play the same way, with the same scripts and the same battles. The importer writes the first kind of file for an imported game; a creator writes the second by hand. Each key is in the reference.

  • Battle rules. Every game plays by the one modern rule set, checked against Showdown. A game chooses what it offers (for example tera = true in [rules]), not how a rule works. A game that wants a different rule declares an override in its own crate (see Your own battle mechanics).
  • Values from a game’s files. A camera table, a light table or a menu’s layout read from a reference game is written by the importer into that game’s folder. The engine holds format knowledge and its own values only (decision 158).
  • An engine change justified by an imported game must name the general case it serves, or it stays in the importer (decision 158, made strict by 204).
  • Importers write settings and content; they never add a path in the engine for one game (plan 18).
  • Planned (plan 25): a test that fails when code under crates/ names a reference game or an import profile. The schema it belongs to is built; the test is not yet.