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.
Rationale
Section titled “Rationale”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).
Profile
Section titled “Profile”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.
Example
Section titled “Example”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 = trueantialias = 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.
Non-settings
Section titled “Non-settings”- Battle rules. Every game plays by the one modern rule set, checked against
Showdown. A game chooses what it offers (for example
tera = truein[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).
Enforcement
Section titled “Enforcement”- 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.
Further reading
Section titled “Further reading”- Game settings (game.toml) for a worked tour of the groups.
- Importing games for what an importer writes.
- What is built today for which features exist.