First import
Overview
Section titled “Overview”An import is a one-way conversion of a game you own into an ordinary PokeLoom
project: maps you can open in Tiled, pieces as OBJ models, pictures as PNG, the
game’s data as PBS text, its text as text files, its events as scripts in PokeLoom’s
language, and settings in game.toml.
From then on the project is like any other. ploom build and ploom run do not know
it was imported. You change it by editing files, not by reverse engineering bytes.
What an import is not:
- Not a ROM editor. Nothing is ever written back into a ROM, and no patch is made.
The way to play the result is
ploom build, which makes a PokeLoom game. - Not an emulator. The original game’s code does not run. Its maps, scripts and data are converted into the engine’s own formats, and the engine runs them.
- Not a path in the engine. Importers write settings and content; they never add code to the engine for one game (One model, many games). When an imported game needs something the engine lacks, either the engine gains a general feature that a new game would also want, or the import writes a named stub: a script line that keeps the original command’s name and is counted in the import’s report.
Battles play by the engine’s modern rules, checked against Showdown, with the imported game’s teams and encounters (decision 238).
Supported games
Section titled “Supported games”| Game | From | Profile | Plays today |
|---|---|---|---|
| Platinum | ROM | gen4-pt |
Its opening through the first wild battle; the first town to the first route can be walked |
| HeartGold | ROM | gen4-hgss |
From the bedroom through the starter to a won wild battle, on desktop and DS |
| Black | ROM | gen5-bw |
The bedroom’s scene to the first battle, on desktop |
| Emerald | Decompilation | gba-emerald |
From its opening through the starter to the first battle, on desktop and DS |
| Black 2 | ROM | gen5-b2 |
Its text and its C-Gear only |
“Plays” means a new game runs that far with its own maps and scripts. Past that point the import still converts the rest of the game, but scripts meet stubs and features the engine does not have yet. SoulSilver and White are planned as settings of their pairs; the generation 1 to 3 games and Diamond and Pearl are designed in plan 35 and not scheduled.
How close each looks to the original is measured, not judged by eye: see Fidelity by pairs.
Command
Section titled “Command”From a ROM, dumped from a cartridge you own:
ploom import platinum.nds games/platinumThe importer reads the ROM’s header (its game code and revision) to choose the profile: which game it is and which readers to use. The command’s summary prints the profile it chose.
From a decompilation’s source tree (pret’s layout), for Emerald:
ploom import --decomp path/to/pokeemerald games/emerald --profile gba-emeraldThen build and play it as any project:
cd games/platinumploom buildploom runOptions:
| Option | Does |
|---|---|
--stage <list> |
Only these stages, comma-separated. The ROM is always unpacked first, the assets organized and the report written last |
--force |
Redo every stage, even those whose inputs are unchanged |
An import runs in stages: graphics, text, data, item icons, maps, props, ground, events, scripts, audio, title, menus and others. Each stage hashes what it reads and is skipped when nothing it reads has changed, so a second run is quick.
Output
Section titled “Output”| Path in the project | What it is |
|---|---|
game.toml |
The game’s settings, as the importer read them: rule presets, cameras, light, the lower screen, sounds, music rules |
maps/ |
One folder a map: map.tmj for Tiled and map.toml; world.toml joins them into one world |
scripts/ |
The events, as .pfs scripts, with stubs by name |
text/, text.txt |
The game’s text, in banks |
pbs/ |
Species, moves, items, trainers and encounters as PBS text |
graphics/ |
Characters, creatures, trainers, battle scenes, the interface, item icons |
audio/ |
Music converted to tracker modules, sound effects and cries |
assets/<source>/<family>/<role>/ |
The world’s pieces organized by role (a door, a tree, a ledge), each folder with an assets.toml and a preview of each asset |
art/<source>/ |
The art set made from those folders |
import/report.md |
What was converted, what was not, and every stub with its count |
import/maps.toml, text.toml, tags.toml |
Your options for the next import: where a new game starts, how many maps, rewrapping text, corrections to roles |
.ploom/import/ |
The importer’s cache: the unpacked ROM |
ploom assets lists the organized assets. Because art is grouped by role, an
imported game can be drawn in another game’s art; see Asset roles and style
chains.
Re-importing
Section titled “Re-importing”Run the same command again after a new version of PokeLoom, or with other options.
Only what changed is redone, and files you edited are kept: a text file is
merged, and any other file you changed gets the new version beside it with
.imported added to its name, for you to compare. Files the importer wrote last
time and no longer writes are removed.
Why this matters: an import is a starting point you keep working on. Improvements to the importer should reach your project without wiping out your changes.
Privacy
Section titled “Privacy”An imported project holds the original game’s maps, art, music, text and data. It is for your own use, and it never belongs in a public repository.
ploom importrefuses a folder git would commit from. A folder outside any repository, one the repository ignores, or a repository of its own is accepted.- It writes a
.gitignoreinto the project for its cache and build output. - Inside the PokeLoom repository, imports go under
games/, which git ignores. ROMs and decompilations go underexternal/, also ignored. - Nothing from a ROM enters the PokeLoom repository, its tests or its history (hard rule 1). The importer is format knowledge only; its tests build tiny files of their own in code.
A game you mean to share is your own work built with the engine: your own maps, art, story and data, or openly licensed ones.
Next steps
Section titled “Next steps”- Importing games: the importer in full, its sources, stages and limits.
- Asset roles and style chains: drawing one game’s world in another’s art.