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.
Overview
Section titled “Overview”- 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).
Sources
Section titled “Sources”| 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.
Support
Section titled “Support”| 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.
Stages
Section titled “Stages”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 |
Re-importing
Section titled “Re-importing”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.
Assets
Section titled “Assets”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.
Private data
Section titled “Private data”| 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.
Other sources
Section titled “Other sources”ploom fetch-datafetches Showdown’s creature data, andploom fetch-pbs <folder>copies a PBS folder you supply, both into git-ignored folders (Creatures and data).ploom fetch-spritesandploom fetch-trainersfetch 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 sheetandploom battle-picconvert 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
Section titled “Planned”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.