Importer
What an import is and how a creator runs one is in importing games and a first import. This page is the machinery.
- A one-way converter on top of the engine. A ROM or a decompilation tree goes
in; an ordinary project comes out: the same folders, formats, script language,
pack and runtime as any other.
ploom buildandploom rundo not know a project was imported. - Importers write settings; they never add a runtime path for one game. When an
imported game behaves differently from the engine’s defaults, the importer writes
that difference into the project: a key of
game.toml,map.tomlorlights.toml, a light table, a camera preset, a menu style record, a script. The engine never asks which game it is running (see one model). - The gate for engine changes. When an imported game needs something the engine lacks, one question decides: would the creator of a new game want this? If yes, it becomes a general engine feature under its own plan, named by the general case it serves. If no, it stays a named stub in the imported project, readable and counted (decisions 158 and 204).
- Not a ROM editor. It never writes a ROM, a patch or a ROM structure.
- Format knowledge, no content. The source of
pl-importknows layouts, record sizes and where to look. It holds no names, strings, tables or hashes of any game’s files. Its tests build tiny synthetic files in code. Its output goes only to a folder git ignores: it refuses a folder git tracks and writes a.gitignoreinto the project (hard rule 1). - Battles play by the engine’s rules with the imported game’s data, on the one shared modern data set.
Structure
Section titled “Structure”ploom import <rom> <project> (tools/pl-cli) calls pl_import::main. Each stage
can run alone (--stage data,text); --force runs them all again.
source ──► rom stage (cache) ──► content stages, in table order ──► report stage reader ──► model ──► writerThe cache and the rom stage
Section titled “The cache and the rom stage”<project>/.ploom/import/ (cache.rs) can be deleted at any time; the next run
rebuilds it. The rom stage, always first, unpacks the ROM’s filesystem, decompresses
the executable and overlays, writes an index and chooses the profile. Each content
stage keeps its key, its report, the indexes it leaves for later stages, and a
pristine copy of every project file it wrote.
A decompilation tree is a source like a ROM: a tree source stage indexes it in place
of rom, and the profile (--profile) chooses its readers (decisions 259, 266).
The stage interface
Section titled “The stage interface”A stage is a row of plain functions, no traits (stage.rs):
pub struct Stage { pub name: &'static str, // as given to --stage; the cache folder pub version: u32, // bumped when the same input gives other output pub needs: &'static [&'static str], // stages whose indexes it reads pub inputs: fn(&RomCache) -> Result<Vec<Input>, String>, pub run: fn(&mut Cx<'_>) -> Result<(), String>,}For each selected stage the runner:
- asks
inputswhat the stage will read; - hashes those inputs with the stage’s name and version into a key, and skips the stage when the key equals the last successful one;
- otherwise calls
runwith aCxthrough which the stage reads only what it declared, leaves indexes, writes project files and fills its part of the report; - records the key, the report and the files in the manifest, and removes files the stage wrote last time but not now.
Declared inputs are what make a second run quick and correct: a stage whose inputs did not change is not run, and a stage cannot read something that would not be in its key.
The stages, in order
Section titled “The stages, in order”STAGES in stage.rs, each a module under src/stages/:
| Stage | Writes |
|---|---|
graphics |
pictures and the project’s font (first: the text stage measures with it) |
text |
text banks and the string index later stages use |
data |
the PBS data folder |
itemicons |
item icons, named by the data’s identifiers |
maps |
maps, game.toml, maps/world.toml |
props |
prop models and their textures |
ground |
the ground pieces and layers |
events |
the events layer of each map |
scripts |
.pfs scripts, import/names.toml |
audio |
music and sounds |
title |
the game’s title, intro and main menu as data |
menus |
menu style records |
gadget |
a touch-screen device’s shell and apps (plan 45) |
assets |
every asset organized by role (plan 40), last |
The rom stage runs first and the report stage last; neither is in the table.
PLANNED, the list of plan 18’s stages not written yet, is empty.
Decoded model
Section titled “Decoded model”Every importer reads into one model (src/model/, task 32a): events, ground, maps,
pictures, props, records, scripts, tiles. A content stage is a reader that the
profile names, which decodes one source’s formats into a model type, and one shared
writer, which writes the project from that type only. Its rules:
- A key of a project file is written from a typed field.
- A feature a source lacks is an empty field, not another writer.
- What a reader decoded is counted in its part of the report; the writer adds nothing format-specific.
- Rules (behaviour tables, movers, arrival) are data or tables a reader names, never a branch on the game in a writer.
Why: before the model, each new game grew branches in the writers, and the differences between games ended up as code. With the model, the differences are fields, and fields become settings in the project, which is where the one-model rule wants them.
Profiles
Section titled “Profiles”A profile is format knowledge for one game revision, chosen by the header’s game code and version byte: which archive holds what, record sizes, where tables sit in the executable or the signatures to search for. Every language of one game shares a profile. An unknown game still runs the generic stages and the report says no profile matched.
The plan allows one fingerprint a revision, to tell a stock executable from a patched one. None is carried in the repository yet: whether even that hash may be committed is the owner’s question. Until then every executable is reported as unknown, and the fingerprint is written only into the git-ignored project.
Re-importing
Section titled “Re-importing”Output is deterministic: the same source, tool version, names file and options give byte-identical files (sorted keys, fixed number formats, no timestamps).
import/manifest.json records every file the importer wrote and its hash
(writer.rs). On a re-import, for each file:
| The user… | The new import… | Result |
|---|---|---|
| did not change it | replaced | |
| changed it | equals the old one | left alone |
| changed it | differs, and it is text | merged three-way (merge.rs), conflicts marked |
| changed it | differs, and it is not text | kept; the new one written beside it as .imported |
| deleted it | stays deleted |
Names. A ROM has numbers. Generated names come from use (a flag that only hides one
person, a flag set beside one gift) or fall back to a number. All of them are in
import/names.toml, which the creator edits; a re-import of the scripts stage reads
it and rewrites every use. The repository ships no list of names for any game.
Coverage report
Section titled “Coverage report”report.rs joins every stage’s counts into import/report.md and
import/report.json, headline numbers first: how much was readable, how much
builds, and how much runs (scripts with no stub, and lines). A headline whose
whole is 0 says “not yet”. Stages may add their own figures for tracking over time.
Sources
Section titled “Sources”ploom source (source.rs, plan 40) lets a project read assets from several games.
Each source is imported once into a source image, an ordinary project in the
per-user cache keyed by the SHA-256 of the source (a ROM’s bytes, or a tree’s folder,
commit and profile). Projects that read the same source share its image. ploom restyle lays a content source’s maps down in the project’s own 3D style with art
from its style chain (see assets and style chains).
- Each format module has a test-only builder that writes a tiny valid file in code
(an archive of two files, one chunk, an event file, a script, a text bank, a
picture); the test parses it back. The builders are
#[cfg(test)]: the shipped tool cannot write these formats. - Decompiler tests from synthetic bytecode: each flow shape decompiles to
.pfsthat compiles and runs with the same observable calls. - Determinism (import twice, compare bytes) and re-import (edit, re-import, the edit survives).
- End to end with a real ROM, ignored by default and run only on a machine that has
one (
PL_ROM=... cargo test -p pl-import -- --ignored): structural invariants only, no expected content.
How close an import looks to the original is measured separately, by pairs.
Changing a stage
Section titled “Changing a stage”- Bump the stage’s
versionwhenever the same input would now give different output; that is what makes cached output stale. - Declare every input in
inputs; a stage reads nothing else. - Put a new feature’s difference in the model as a field and write it as a setting. If the engine cannot express it, the change belongs to an engine plan, argued by the general case, not to the importer.