Skip to content

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 build and ploom run do 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.toml or lights.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-import knows 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 .gitignore into 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.

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 ──► writer

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

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:

  1. asks inputs what the stage will read;
  2. 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;
  3. otherwise calls run with a Cx through which the stage reads only what it declared, leaves indexes, writes project files and fills its part of the report;
  4. 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.

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.

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:

  1. A key of a project file is written from a typed field.
  2. A feature a source lacks is an empty field, not another writer.
  3. What a reader decoded is counted in its part of the report; the writer adds nothing format-specific.
  4. 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.

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.

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.

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.

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 .pfs that 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.

  • Bump the stage’s version whenever 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.