Skip to content

Importing

An import is a one-way conversion of a game you own into an ordinary PokeLoom project folder: Tiled maps, OBJ pieces, PNG pictures, PBS data, text files and .pfs scripts. After that, changing the game means editing plain files, not reverse engineering. ploom build and ploom run do not know the project was imported.

  • It is a converter on top of the engine. ROM or source tree in, project out. The project uses the same formats, script language, pack and runtime every creator uses.
  • It is not a ROM editor. It never writes a ROM, never produces a patch and never edits a game in place. The way back to something playable is ploom build, which makes a PokeLoom game.
  • It never adds a path for one game to the engine. No compatibility layer, no emulated script machine, no special case for an original in any crate that runs. When an imported game needs something the engine lacks, the question is whether a creator of a new game would want it too. If so, it becomes a general engine feature with its own settings; if not, it stays a named stub in the imported project, readable and counted in the report. This is why one engine can run five different games: their differences are settings (One model).
  • Battles play by the engine’s modern rules, checked against Showdown, with the shared modern creature data. An import keeps its original’s out-of-battle rules as settings (the experience formula, the day care, the wild roll).
Source Command Profile
A DS ROM: Platinum ploom import <rom> <project> gen4-pt, found from the ROM’s header
A DS ROM: HeartGold the same gen4-hgss (SoulSilver’s header is accepted; no SoulSilver ROM has been tried)
A DS ROM: Black the same gen5-bw (White’s header is accepted; only Black has been imported)
A DS ROM: Black 2 the same gen5-b2: its text and its touch-screen gadget only, for now
Emerald’s decompilation tree ploom import --decomp <tree> <project> --profile gba-emerald gba-emerald

A profile is format knowledge for one game: where its archives are, how big its records are, how its text is encoded. It holds no content. Emerald is imported from its decompilation’s source tree, never a ROM, so its import has the original’s own names for maps, flags and scripts. The DS games come from ROMs today. A decompilation gives better names and is the ground truth to check a ROM reader against; models, textures and sound stay binary in every tree, so they keep coming from the ROM.

Planned (plan 26): DS games’ events, scripts and tables read from their decompilations’ sources beside the ROM, which supplies what the trees leave binary. Only a prototype exists: ploom decomp-diff <tree> compares Platinum’s events from its tree with the import’s own from the ROM.

Game From How far it plays
Platinum ROM builds and plays its opening through the first wild battle; its title, intro and menus are its own; seven of ten places checked against the real game pass
HeartGold ROM plays its opening to the choice of a starter, with its cameras, clock, light and follower
Black ROM its opening plays to the first battle on desktop; its people, cameras, seasons and light are its own
Emerald decompilation the tile-map style: its new game plays through the first battle; its data, pictures, title, music and menus are its own

“Checked against the real game” is the pairs method: the real game and the import pictured at the same place and hour, the difference counted by a tool (Fidelity pairs). What is not imported is code: the original’s battle engine, menus and native scenes are provided by the engine, or listed as missing.

An import runs in stages, each writing its part of the project and of the report. The ROM is always unpacked first, into a cache in <project>/.ploom/import/, and the report is written last.

Stage Writes
graphics pictures, the font, character sheets, battle pictures
text text banks, with only the engine’s control codes
data pbs/: trainers, encounters, items, the game’s rows
itemicons item icons
maps, props, ground maps, placed models, the ground as pieces, worlds
events people, warps, signs and triggers on each map
scripts scripts/, with commands the engine lacks kept as named stubs
audio music as tracker modules, sound effects and cries
title, menus, gadget the title and intro, menu styles, the touch-screen gadget
assets every asset organized by role (below)

--stage text,data runs only those stages; --force redoes every stage. Each stage is keyed by the hash of its inputs, so a second run does only what changed.

The import writes import/report.md: what was converted, what became a stub, what was left out and why. Options it reads again on every import live in import/:

File What it sets
import/maps.toml start and start_at: where a new game begins; limit: only the nearest maps
import/text.toml rewrap = true: rewrap lines too wide for the engine’s text box
import/tags.toml your corrections of assets’ roles (ploom assets tag)
import/names.toml readable names for the original’s flags and variables, used by every script

Import again whenever the importer improves: a new mapping turns stubs into commands. The output is deterministic (the same input and tool version give byte-identical files), and your edits are protected file by file:

  • a file you did not change is replaced;
  • a text file (.pfs, .txt, .toml, PBS) changed by you and by the import is merged three ways, conflicts marked;
  • any other file you changed is kept, and the new version is written beside it as <name>.imported;
  • a file you deleted stays deleted; a file the import no longer writes is removed.

git init in the project (a private repository on your machine) gives the same safety by ordinary means.

The last stage sorts every asset into assets/<source>/<family>/<role>/ with a readable name, a sidecar assets.toml that keeps the original name, and a preview. Every tree of one game is then in one folder, and an art set for drawing other games in this one’s look is generated from those folders. ploom assets lists them. This, sources and drawing one game in another’s art are on Asset roles and style chains.

Place What
The project folder the imported game. Keep it outside any public repository; in the engine’s own repository the convention is games/<name>/, which git ignores
<project>/.ploom/import/ the unpacked ROM and stage caches; deletable at any time
The per-user cache (~/.cache/ploom/sources/ on Linux) source images read by ploom source, shared by every project that uses the same source
Your ROMs and decompilations wherever you keep them; sources.toml and the import name their paths

Tests of the importer build tiny synthetic files in code; no ROM, extracted file or count from a game is in the repository.

  • ploom fetch-data fetches Showdown’s creature data, and ploom fetch-pbs <folder> copies a PBS folder you supply, both into git-ignored folders (Creatures and data).
  • ploom fetch-sprites and ploom fetch-trainers fetch creature and trainer pictures for a game you do not share.
  • ploom import-midi <song.mid> <instruments.txt> <out.xm> turns a MIDI file into a tracker module with the importer’s own converter.
  • ploom sheet and ploom battle-pic convert pictures drawn for other engines (Art).

The full list with arguments is the command reference. How the importer is built inside is on The importer.

Planned (plan 35): importers for the Game Boy, GBA and remaining DS games, all writing the same project formats, all playing by modern rules on the shared creature data.

Planned (plan 40): picking assets from a source into an existing project (ploom import <source> --asset <id> --into <project>), with their dependencies, renames and numbers remapped and a ledger so a later re-import keeps your edits; and a --share check that refuses a build holding any asset read from a ROM or a tree.