Fidelity pairs
Method
Section titled “Method”“Looks right” is not evidence. When PokeLoom claims an imported game looks like the original, it shows a pair: a picture of the real game and a picture of the engine, taken at the same place and moment, with the difference counted by a tool.
A pair is taken at the same:
- map and cell, and the player’s facing;
- in-game hour and date: both sides start from one fixed clock, so light, shadows and lit windows are compared like for like;
- story state: the same flags and variables, so the same people stand in the same places.
The real side runs the original game in melonDS, hidden and silent, continued from a save made by playing it. For Platinum the tool stops the emulator and reads every character’s cell and facing from the game’s memory in the frame it takes. The engine side plays a copy of the import from a save of its own made from the real one: the player’s place and every flag and variable the import names, with the characters put on the cells the real game had them on.
cargo xtask pairs platinumEach game is a profile, a small data file in xtask/pairs/ listing where the ROM,
the import and the private files are, how its saves are read, and its places:
[place.town-night]title = "FIRST TOWN"save = "town"hour = 21The output, for each place, is three pictures side by side (real, ours, the difference) with the numbers written on them, and a summary.
Grading
Section titled “Grading”A 3D picture is never identical to the original: a light a step off tints every colour a little. A count of “pixels that differ” would mix that up with real bugs. So each pixel is graded by its largest channel difference, out of 255 (decision 302):
| Grade | Difference | What it usually means |
|---|---|---|
| Same | 16 or less | One step of the DS’s colour channels, or rounding |
| Shade | 17 to 48 | The same thing lit or tinted a little differently |
| Wrong | over 48 | Something else is there: a missing or moved object, a texture out of place, the sky where a roof should be |
A 3D place passes at 3 % wrong or less. Shade is reported, not failed. Three more checks say where the wrong pixels come from:
- Shift: the whole-picture offset of ours with the fewest wrong pixels. Anything but none is a camera or placement bug.
- Edges: how far the outlines of the two pictures agree. A moved object lowers it; a light that is off leaves it alone.
- Blobs: the wrong pixels in groups, largest first, with their boxes, so a missing object shows as one named blob.
A 2D screen (a menu, a tile map) passes at 1 % of pixels over 16: the DS’s 2D
hardware leaves no excuse for shading differences. A place can compare both
screens, each judged by its own kind, and a run of frames (a menu opening, a
transition), lined up at their first change and compared frame by frame. Menu pairs
can drive the pen on both sides (tap, touch, drag).
The owner’s fidelity rule behind the numbers: pixel perfection with the DS games is the aim where possible (decision 201), without making the engine more convoluted for it (decision 206).
Why a tool
Section titled “Why a tool”- Numbers do not drift. “Close enough” changes with the viewer and the day. A number either passes or does not, and it is written down with what is wrong.
- They find the cause. The shift, edges and blobs point at the class of bug (a camera, a light, a placement) before anyone opens the code.
- They show progress. A fix moves a number. Platinum’s first town at night went from 2.2 % to 83.9 % equal pixels when imported models were lit by the DS’s hardware lights as the original lights them (decision 288).
- They catch regressions. A change that helps one game and hurts another shows in the other game’s pairs.
Status
Section titled “Status”As last measured, on desktop:
| Game | Passing | Not yet |
|---|---|---|
| Platinum | The first town by day and at night, the first route, the second town, a house: each under 2 % wrong | The lab and the healing centre, about 4 to 5 % wrong |
| HeartGold | The player’s room, the first route | The first town by day and at night |
| Black | None yet | The first town in the late afternoon is closest, about 3.3 %; the first route and the room are further off |
| Black 2 | — | Its profile exists and boots to the C-Gear; its places wait for a save to start from |
Platinum’s menus are compared the same way on both screens: its party screen meets the 2D mark as a built-in style; its summary’s memo page does not yet. Emerald’s first maps were checked against the decompilation’s own build running in mGBA, by the tile-style work; mGBA is not in the pairs tool yet.
Private references
Section titled “Private references”The real side of every pair is the original game: its art, its maps, its characters. None of it may enter the repository (hard rule 1), and none of it can be published.
- The ROM, the saves and the real pictures live under
games/andexternal/, which git ignores. The pictures the tool writes go to the build folder (target/). - What is in the repository is only the tool and each game’s profile: paths, how to read a save, and the list of places by map and hour. No picture, no value read from a game.
- CI cannot run pairs, since it has no ROM. Their evidence is the numbers, recorded with each change, and the pictures shown privately.
This is also why one command re-takes every place of a game, both sides: a picture nobody can re-take could silently be old, and only the numbers leave the machine.
Further reading
Section titled “Further reading”- Import a game you own.
- How the field cameras work and How light follows the hour, the two things pairs most often find wrong.
- Testing for the engine’s other comparisons.