Skip to content

Battle rules

PokeLoom has one set of battle rules: the current generation’s, as Pokémon Showdown plays them. A game does not pick “generation 4 damage” or “generation 5 critical hits”. The reason is checking: every built-in mechanic is proven against Showdown by playing the same battles in both and comparing every line and every random number (Showdown conformance). One rule set can be proven once; a menu of old rules would each need a reference of their own. Imported games play by these rules too (decision 238).

What a game does choose is smaller and sits around the battle: rules a new game starts with, which gimmicks exist in it, and how the battle looks and sounds. A game that needs a rule that is really different, an old quirk or an invented mechanic, writes it as its own mechanic (Your own battle mechanics).

[rules] in game.toml holds the rules a new game starts with. Every key is off without its line. The sample keeps HeartGold’s day care and lets field moves stay learnt:

[rules]
daycare = "heartgold"
keep_field_moves = true

The rules that touch battles:

Key What it does
lose_money a lost battle costs money ("by_badges"); without it, nothing
level_cap no creature trains past this level, and a capsule thrown at a wild creature above it is not used
exp_all experience to every creature of the party that can fight; those not in the battle get half
no_battle_items the bag in a battle lists capsules only
battle_style "shift" or "set"
tera the player’s creatures may terastallize
challenge the challenge mode (permadeath) and its sub-rules

Two notes on the state of these. The battle style is stored and scripts can read it, but neither style offers the switch when a foe faints yet: the shift style’s prompt is not built. And lose_money takes money by the strongest creature’s level, as the games do with no badge; the scale by badges is not built yet.

Beside them sit presets for systems around battles: daycare, wild (what the lead’s ability and item do to wild encounters, and how roamers move) and bag. Each is "modern" by default or the name of one game whose rules it copies: "emerald", "platinum", "heartgold", "black2". They are presets rather than separate switches because each game’s rules come as a set that only make sense together.

Every key, its range and its default are in the game.toml reference.

game.toml is only where a game starts. A script reads a rule with rule and changes it with setrule; from then on the rule is kept in the save. The sample’s gate watchman sets a level cap when he is beaten (scripts/town.pfs):

if lastresult() == 1 {
set BEAT_GATE_WATCH
setbadge 0
setrule level_cap, 20
}

The rule words are in the script language reference. Options the player sees, cheats and level caps by hook are on Rules, options and cheats.

[battle] and its tables hold the battle’s look and sound: the surfing scene, the low-health warning, music and effects. Nothing there changes how a battle plays. See Battles and trainers.

The modern games each add one battle gimmick: a once-a-battle transformation chosen with a move. PokeLoom plans all four, each checked against Showdown in the mode where it exists, and each through the same path: a choice on the move menu, a flag of who may still use it, an action that runs before moves, and a line and flash on the screen. A new gimmick adds a row to each of these, not a new mechanism.

Gimmick State How a game uses it
Mega Evolution built; 50,000 fuzzed battles with no mismatch a creature holding its mega stone may Mega Evolve once a battle
Terastallization built; 50,000 fuzzed battles with no mismatch tera = true in [rules]
Z-Moves and Ultra Burst Planned (plan 36) a Z-crystal held
Dynamax and Gigantamax Planned (plan 36) once a side a battle

A creature that holds its stone may Mega Evolve once a battle, one creature a side. The move menu shows a toggle only while it can. Trainers Mega Evolve the first time they can; wild creatures never do. A game’s own mega is data: a form of the species that names its stone, and an item with the MegaStone flag. The sample’s Bramblemane has one:

pbs/pokemon_forms.txt
[BRAMBLEMANE,1]
FormName = Full Bloom
MegaStone = BLOOMSTONE
BaseStats = 82,110,121,80,128,109
pbs/items.txt
[BLOOMSTONE]
Name = Bloom Stone
Flags = MegaStone,Fling_80

The ranger Odell’s second team holds it (Item = BLOOMSTONE in pbs/trainers.txt), so his Bramblemane blooms in battle. A game that does not want Mega Evolution gives out no stones. Planned (plan 08): a switch in the game’s format that turns each gimmick off.

Two details follow from one rule set: speed after Mega Evolution is counted as in generation 9, and a move’s mega (as for Rayquaza) follows the National Dex rules. Two stones of a game’s own for two mega forms of one species cannot yet be told apart.

With tera = true, each of the player’s creatures may terastallize into its tera type, one a battle. The same move-menu button serves Mega Evolution and tera. A trainer’s creature can terastallize only when its party entry names a type, and does so the first time it can; wild creatures never do:

Pokemon = KILNBACK,40
TeraType = EMBER

A script can switch it on later with setrule tera, 1, for a game that grants the power partway through its story. Link battles keep the Terastal Clause.

No official game or Showdown mode has all four gimmicks, so there is no reference for mixing them. The engine’s rule (plan 08): each side may use each allowed gimmick once a battle; one creature uses at most one; a creature holding a mega stone or a Z-crystal cannot Dynamax. These cross-gimmick rules are covered by the engine’s own scenario tests, not by Showdown.

Each gimmick has a code-size budget on the DS, measured when it is built: Mega Evolution 8 KB (measured at under 5 KB), Terastallization 12 KB, Z-Moves 24 KB, Dynamax 40 KB. All four together must leave the battle engine within its 900 KB share of the DS’s code budget (Budgets). A gimmick that goes over is made smaller; content is never dropped to fit.

An import of a handheld game keeps that game’s rules outside battle as settings: its day care, its wild rules, its bag (decision 206). That is why the presets above are named after games. Inside battle, an import plays by the one modern rule set, with modern creature data (decision 238). A creator who wants an old battle quirk back writes it as an override of the built-in mechanic, declared and tested like any other (Your own battle mechanics).

That each importer writes its game’s presets into the import’s [rules] today is not verified on this page; check the import’s game.toml after importing.

Planned (decision 206): the experience formula is a setting, so an imported game can keep its own levelling pace; a new game defaults to the modern formula.

Planned (plan 34): rule knobs. A game may change a named constant of the battle core, such as the critical-hit multiplier or burn’s damage factor, as a declared override. Each knob’s default is Showdown’s value, and the engine’s own checks always run with the defaults.