Skip to content

Custom mechanics

Every built-in mechanic of PokeLoom is ported from Pokémon Showdown and checked against it (Showdown conformance). That is a guardrail: a creator can trust that Leech Seed or Intimidate behaves as it does in the official games, in every order of events.

Fan games want more: their own moves and abilities, field effects that change every move, bosses with several health bars, a burn that hurts less. PokeLoom lets a game add any mechanic and replace any built-in one (decision 230), on three conditions:

  • Declared. A change is named in the game’s data or crate, never hidden.
  • Reported. The build lists every mechanic the game adds and every one it changes.
  • Tested by the game. The game’s own scenario tests cover what it changes. The engine’s conformance runs never include a game’s changes, so no game can weaken them.

A change reaches effects and named knobs only (decision 235). A game never patches the battle core. Something deeper, such as a new step in the damage formula, becomes a new engine event or knob with Showdown’s behaviour as its default. Every point of change is named, so it can be listed, tested and documented.

A custom mechanic is an effect like a built-in one: rows of (event, scope, order, priority, run) that the battle’s dispatcher gathers, sorts and calls exactly as it does Showdown’s. Only how run is written differs:

Route For Runs as State
(a) Data most custom moves; many abilities, items and field-effect tables records read by fixed, parameterised handlers partly built: reuse of existing effects. Planned (plan 34): primitives
(b) Script hooks logic data cannot say, written without Rust battle procedures in the script language, compiled to bytecode Planned (plan 34)
(c) Rust heavy or unusual logic: field effects, bosses, formats, overrides plain functions in the game crate’s static tables built in the game crate’s tests; not linked into a runtime yet

Because the dispatcher does not change, a battle with no custom effect gathers exactly the listeners it would without the game, so it draws the same random numbers in the same order as Showdown.

What a game can do with data today, with no code:

  • A new type is a section of pbs/types.txt, with its weaknesses, resistances and immunities. Nothing in the engine lists types.
  • A new move is a section of pbs/moves.txt. It may do plain damage of any type, power, accuracy, priority and target; change stat stages by an Essentials function code such as RaiseUserAtk1Spd2; inflict a status (BurnTarget); or behave as a built-in move of the same identifier.
  • A new ability or item may name a built-in behaviour with Effect =.

ploom pack --coverage lists every function code the data uses and whether the engine runs it. A code it does not understand compiles as plain damage, so check the report before relying on one. Creatures and data covers moves and types in full.

Planned (plan 34): primitives. About thirty parameterised families (power under a condition, a type change, a stat multiplier, an immunity that heals, an effect on contact, an end-of-turn effect, and so on), each listening to the event Showdown uses for that kind of effect. A move, ability or item composes them in Effect = lines. From the plan:

[STEAMBURST]
Name = Steam Burst
Type = WATER
Category = Special
Power = 70
Accuracy = 100
TotalPP = 10
Effect = power_if weather:RAIN 2/1
Effect = then chance:30 user stage:SPEED +1

A row costs about 8 bytes, and only the rows of the creatures in a battle are loaded. ploom check refuses an unknown family, condition or parameter and names the line.

Planned (plan 34): a battle module (battle/*.pfs) declares effects in the script language, each with its handlers on battle events. From the plan:

ability EMBERHEART "Emberheart" {
on BasePower -> value {
if move.type == FIRE and hp(self) * 3 <= maxhp(self) { return modify(3, 2) }
}
}

A battle hook runs to completion inside the event, so it may not wait: say, wait and movement are compile errors there. It has a budget of 4,000 instructions a call and at most 8 nested hooks; past either, the hook stops and the battle logs a fault, the same on every platform. Its randomness comes only from the battle’s own random numbers. Only the hooks of effects present in a battle are loaded. Script hooks suit a creator who writes no Rust, a mechanic of a few lines, and live reload on desktop; heavy mechanics belong in Rust.

A project with a Cargo.toml is a game with Rust of its own. The game crate gives the engine one static BattleExt: tables of abilities, items and move callbacks written exactly as the engine’s own are, the names the data reaches them by, and the overrides. templates/game-crate is the template. It adds an invented ability, an invented move of an invented type, and overrides one built-in ability:

/// `ModifyAtk`, at the engine's Huge Power priority: half again, not double.
fn mighty_modify_atk(_: &mut Battle<'_>, ctx: &mut EventCtx) -> Relay {
ctx.chain_modify(3, 2)
}
static MIGHTY: [Handler; 1] = [Handler::on(EventId::ModifyAtk, mighty_modify_atk).priority(5)];
/// Built-in effects this game replaces.
static OVERRIDES: [Override; 1] = [Override {
kind: ExtKind::Ability,
identifier: "hugepower",
row: ability::MIGHTY,
source: "src/lib.rs",
}];

How the pieces connect:

  • Names. Each of the game’s effects has an identifier. The data reaches it by that name: an ability’s or item’s Effect = line in PBS, or a move with no FunctionCode, whose behaviour is its own identifier. A new move is its data in moves.txt plus a handler table named after it.
  • Numbers. A game’s rows have bit 15 set in the effect number, so they never meet the engine’s. The pack is stamped with the game’s tables; a pack built for another game, or for none, is refused.
  • Overrides. An Override row redirects every use of a built-in identifier in the game’s data to the game’s row. The engine’s row is never edited: other games and the engine’s own tests still reach it. An overridden effect is the game’s in every way, including the engine’s checks by number, so give the game’s row the flags the engine asks about. Today abilities, items and move callbacks can be overridden; statuses and named volatiles need more work (decision 280).
  • The same limits as the engine. No floating point, no core::fmt, no allocation per event, no random numbers but the battle’s. The template turns on lints for the first.

Handlers call the creator API: the battle’s helpers that built-in effects use (chain_modify, heal, damage, boost, add_volatile, random_chance and the rest), made public with documented contracts in pl_battle::ext. How to write a handler, read a Showdown definition and avoid the traps is in docs/battle-effects.md in the repository; The battle engine explains the dispatcher. Rust extensions covers the game crate as a whole.

Today a game’s battle Rust runs in the game crate’s own host tests and its report. Neither the desktop program nor the DS ROM links a game’s tables yet (decision 280).

Planned (plan 46): the game’s own desktop program and DS ROM are built with its crate inside.

Planned (plan 34): overrides also from data, in a [battle.overrides] table of game.toml or a PBS Effect = line on an official identifier.

ploom build on a project with a game crate runs the crate for its tables (or reads the file --battle-ext names), puts the game’s numbers into the pack, and prints two lists: “this game changes:” (each overridden identifier) and “this game adds:”. Both are also written to build/report.json, so a player or a tournament organiser can see exactly how a game’s battles differ from the official ones.

Official and custom mechanics are tested on two routes:

Built-in mechanics A game’s mechanics and overrides
Reference Showdown the creator’s intent
Tests damage rolls, ported scenario tests, the differential fuzzer the game’s own scenario tests, against a baseline
Run by the engine’s checks the game: cargo test today; ploom test planned
A failure means the engine is wrong the game is wrong, or an override broke something

Today the template’s tests/scenarios.rs builds the pack twice, with the game’s tables and without them, and plays each battle on both. The turns before the custom effect acts must be identical; the turns after show what the game changes and nothing else.

Planned (plan 34): scenario tests as text, tests/battle/*.pbt in a project, run by ploom test without Rust and by one line in a game crate’s cargo test. From the plan:

test "Steam Burst doubles in rain"
format singles
weather RAIN
p1: MYMON lv50 moves STEAMBURST ability NONE
p2: TARGETMON lv50 moves SPLASH
rng: damage max, crit no, hit yes, chance no
turn: p1 STEAMBURST, p2 SPLASH
expect power STEAMBURST 140
baseline: weather NONE
expect diff only power STEAMBURST, damage p2

baseline: replays the test with something changed and expect diff only says which observations may differ: that is how a creator shows a custom mechanic touches nothing else. ploom check lists every override no test names.

Planned (plan 34): ploom test --official. It plays a corpus of battles (2,000 by default) using only official identifiers the game does not override, once in the bare engine and once with the game’s tables linked, and requires byte-identical logs. A difference means the game changed something it did not declare.

Planned (plan 34), all on the same effect model:

  • Arenas. A field slot beside weather and terrain, for field effects like those of the large Essentials fan games: tables of type and move power changes, changed moves, end-of-turn effects, transitions to another arena, seeds, and handlers on any event. An arena may replace terrain. The sample is to gain an original arena as the proof, written once in Rust and once in script, with identical logs.
  • Bosses. A creature with several health bars: damage stops at a bar’s end, a bar break raises an event for hooks (a new arena, a shield, a line), and immunities are data on the boss rule.
  • Scripted mid-battle events. Rule hooks at turn start, after choices, at turn end and on any event: a line, music, a change of arena, a question to the player. State changes happen in the rule on the battle’s random numbers; lines and music are log events the screen plays, so replays and AI look-ahead stay exact.
  • Formats. A format is a list of rule effects: facility rules, inverse battles, scripted battles. SOS battles and raids get seams in the core (add a battler mid battle, act more than once a turn, an end condition); their rules live in a game’s Rust, with examples in the template.
  • Custom field moves. The built-in field moves become presets of one table, and a game adds its own with data, a script or Rust (Game systems).

Each has a budget on the DS, set in plan 34: custom mechanics add at most 24 KB of battle memory, a turn with an arena and script hooks takes at most 2 ms on the DS, and a battle with nothing custom has no extra listeners.

Planned (plan 34): a generated reference of every event, primitive, script verb and helper, with a map from Essentials’ battle handlers to PokeLoom’s events, and a written porting guide, so a person or an AI can port a fan game’s mechanics from its source.