Showdown conformance
Every built-in battle mechanic is ported from Pokémon Showdown, and no built-in mechanic is done until a test against Showdown shows it (hard rule 5). The proof is not reasoning about the rules or memory of the games. It is this:
Play the same battle in Showdown and in PokeLoom, from the same seed, the same teams and the same choices. The two event logs must match line for line, including every random number drawn, in the same order.
Why Showdown: it is the most complete and most checked simulator of the modern rules, it is open source (MIT licence), and its code can be read. Why such a strict test: a battle engine can look right for a thousand battles and be wrong in the next, in an interaction nobody thought to try. Matching the random numbers as well as the outcome finds a difference at the exact step where it begins.
Random numbers
Section titled “Random numbers”PokeLoom’s random number generator is Showdown’s own “gen5” generator, with Showdown’s ways of drawing a range, a chance and a shuffle (Determinism and the seeded RNG). Same seed, same sequence.
That alone is not enough. Showdown orders the handlers of every event by priority and speed, and shuffles those that tie, drawing random numbers to do it. So how many numbers an event draws depends on which effects have a handler for it, and at what priority, even handlers that do nothing in that battle. An effect in PokeLoom therefore registers exactly the events its Showdown definition registers, with the same order, priority and sub-order numbers (decisions 7 and 8).
Consequences a contributor meets (from the guide to writing an effect,
docs/battle-effects.md):
- Never write an effect from a description of the rule. Read its definition in Showdown and port it step by step, naming what was ported.
- Register what Showdown registers. An extra or a missing handler changes the numbers drawn in battles where the effect itself does nothing.
- Rolls are drawn even when the outcome is certain, if Showdown draws there.
- Effects are rows of static tables of plain functions, with no data copied: tests use invented creatures and moves; identifiers of real ones are allowed, their data is not.
Fuzzer
Section titled “Fuzzer”The differential fuzzer is in conformance/. For each case number it:
- generates a random battle in Showdown (
conformance/showdown.js): teams, held items, abilities and legal choices, restricted to what the engine supports; - plays it in Showdown and records the log, with every random number drawn;
- replays the same battle in
pl-battleand renders its log in Showdown’s text form; - compares the two, line by line.
cargo run --release -p pl-conformance -- <first-case> <count> [stage]A case number always generates the same battle, so a mismatch is reproduced by running that one case. The report gives the number of battles that match, that differ, and that were skipped as unsupported. Zero unsupported is the goal: an unsupported case tests nothing.
MISMATCH in case 4711: line 212: Showdown "~rng|1350503953", pl-battle "|-damage|..."A line starting ~rng| is a random number drawn. The first line that differs is
where the two battles part: Showdown drew a number the engine did not (an event whose
handlers tie, an effect’s own roll), the engine drew one Showdown did not, or a
message differs.
Stages. The battles are generated in stages. Each stage adds what one batch of work built (a group of moves, abilities or items, the doubles core, Mega Evolution) and favours it, so that half the creatures use the new effects. Combined stages make effects from separate batches meet. Stages are append-only: an old stage always generates the same battles, so every earlier result can be re-run.
Same data on both sides. The fuzzer builds its pack from Showdown’s own data at run time, on the developer’s machine, so a data difference cannot hide a rule bug. Nothing from Showdown’s data is written into the repository.
The checkout is pinned to one Showdown commit. A built checkout lives in
external/showdown, which git ignores; without it, the differential test in
cargo test is skipped with a message.
Coverage
Section titled “Coverage”| Part | State |
|---|---|
| Moves | 818 of Showdown’s 822 in singles |
| Abilities | 279 of 310 |
| Held items | 264 |
| Doubles | The core, with its own fuzzer stages; on the battle screen |
| Multi and tag battles | Fuzzed against Showdown’s four-player doubles; no mismatch |
| Mega Evolution | 50,000 fuzzed battles, no mismatch |
| Terastallization | 50,000 fuzzed battles, no mismatch |
| Z-Moves, Dynamax | Not built (plan 36) |
| Triples | Prepared in the core, not written |
| Rotation | Not written: Showdown has no reference to check it against, so it waits for the owner |
As last reported for singles, 840,000 fuzzed battles ran with no open mismatch. A mismatch found is fixed and its case kept as a regression.
Three layers, as designed (plan 09). The differential battles are the required layer and are built. Some effects also have scenario tests ported from Showdown’s own test suite, with attribution kept in the file. Planned (plan 09): comparing all sixteen damage rolls of generated attacks with Showdown’s damage calculator.
What it does not prove. Interactions that no generated battle reaches, and mechanics Showdown does not simulate. Coverage is therefore reported as volume (battles run, mismatches open), never as “equivalent”.
Limits
Section titled “Limits”Showdown simulates battles, not games. Catching, experience, growth, effort values,
running away, obedience, prize money and friendship are plain functions of their own
in pl-battle (extras), checked against the games and Essentials (where those
disagree, the games win; decision 46). Where the engine’s sources were not certain,
the code says so. The trainer AI’s choices are the engine’s own and are not compared.
Custom mechanics
Section titled “Custom mechanics”A game may add mechanics or override built-in ones (decisions 230 and 235): through data (a new move from existing effects), through script hooks on battle events, or through plain Rust functions in the game’s own crate. These are not Showdown’s, so they are kept apart and made visible:
- Declared. A game’s effects and overrides are rows of its own static tables, numbered apart from the engine’s (bit 15 set). An overridden effect is the game’s in every way; the engine’s row is never edited.
- Reported.
ploom buildon a project with its own crate prints what “this game changes” and what “this game adds”, and writes them tobuild/report.json. - Tested by the game. The game’s scenarios play each battle twice, with the game’s tables and without them, and the turns before the custom effect acts must be the same.
- Never in the engine’s proof. The engine’s conformance runs never link a game crate. The Showdown checks are the engine’s guardrails, not a cage for a game.
Planned (plan 34): ploom test --official, which proves a game leaves the official
mechanics untouched, and creator scenario tests in a short text form. A game’s own
battle effects run on desktop today; on DS after plan 46’s extension. See Your own
battle mechanics.
Further reading
Section titled “Further reading”- Battle rules and gimmicks for what a game chooses.
- The battle engine for the queue, dispatch and effects.