Custom mechanics
Overview
Section titled “Overview”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.
Routes
Section titled “Routes”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 asRaiseUserAtk1Spd2; 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 BurstType = WATERCategory = SpecialPower = 70Accuracy = 100TotalPP = 10Effect = power_if weather:RAIN 2/1Effect = then chance:30 user stage:SPEED +1A 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.
Script hooks
Section titled “Script hooks”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 noFunctionCode, whose behaviour is its own identifier. A new move is its data inmoves.txtplus 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
Overriderow 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.
Build report
Section titled “Build report”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.
Testing
Section titled “Testing”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 singlesweather RAINp1: MYMON lv50 moves STEAMBURST ability NONEp2: TARGETMON lv50 moves SPLASHrng: damage max, crit no, hit yes, chance noturn: p1 STEAMBURST, p2 SPLASHexpect power STEAMBURST 140baseline: weather NONEexpect diff only power STEAMBURST, damage p2baseline: 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.
Large mechanics
Section titled “Large mechanics”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.