Skip to content

First import

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).

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.

From a ROM, dumped from a cartridge you own:

Terminal window
ploom import platinum.nds games/platinum

The 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:

Terminal window
ploom import --decomp path/to/pokeemerald games/emerald --profile gba-emerald

Then build and play it as any project:

Terminal window
cd games/platinum
ploom build
ploom run

Options:

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.

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.

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.

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 import refuses 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 .gitignore into the project for its cache and build output.
  • Inside the PokeLoom repository, imports go under games/, which git ignores. ROMs and decompilations go under external/, 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.