Skip to content

Packages

A package is how creators share a feature: a quest log, a search for wild creatures, a set of new moves. It is a folder of the same files a game has (data, scripts, screens, text, pictures, tests, and optionally a Rust crate) with a package.toml that names it, versions it and says what it needs. A game adds it with one command, and the build layers it under the game’s own files.

The design answers the question Essentials plugins raise: what happens when two of them change the same thing? In PokeLoom that is a build error, with both files and lines, until one package declares that it overrides the other. There is no load order to get wrong.

Planned (plan 46): a package is a folder with package.toml and any of a project’s own folders.

dexnav-plus/
package.toml
pbs/ rows of PBS files (new IDs; existing IDs only as declared overrides)
scripts/ modules: hooks, procedures, battle modules
layouts/ screens, apps, record changes
records/ declared saved records
text/ strings (keys prefixed by the package's name)
graphics/ audio/
tests/ scenario tests and walks, run with the game's
rust/ an optional crate
[package]
name = "dexnav-plus" # [a-z0-9-], unique in a project
version = "1.2.0" # semantic versioning
engine = ">=0.12, <0.14" # the ploom versions it builds with
description = "Chains, search and a radar for wild encounters."
license = "MIT OR Apache-2.0"
repository = "https://example.org/dexnav-plus.git"
[requires]
quest-core = "^1.0"
[settings] # what a game may set, with defaults
chain_max = { type = "int", default = 40, min = 1, max = 999 }
[overrides] # what it knowingly replaces
"script.proc:quest-core.questdone" = "quest-core"
"pbs.item:REPEL" = "engine"

A game sets a package’s settings in its own game.toml, under [packages.dexnav-plus]. Settings are constants at build time, so they cost nothing while the game runs.

Planned (plan 46):

Command Does
ploom add <git-url>[@tag] or ploom add <path> fetches the package, shows what it is about to trust, copies it into packages/ and records it in the lock
ploom remove <name> removes it; refused while another package requires it
ploom update [<name>] takes newer versions within the [requires] ranges
ploom packages lists each package: version, source, what it adds

Packages come from git URLs and local folders; there is no central index yet. A copy lives in the project at packages/<name>/, committed with the game so it builds offline and a reviewer sees the code. ploom.lock records each package’s version, source, revision and a hash of its files.

No edits in place. ploom build checks each copy against the lock and refuses an edited package, naming the files. A change belongs in the game, as an override, or in a fork with its own name. That keeps “version 1.2.0” meaning the same files everywhere.

Planned (plan 46): ploom build reads, in order, the engine’s data, the built-in packages the game turns on, the packages in dependency order, and the game. Every named thing has one owner: a PBS row (pbs.move:TACKLE), a string key, a script procedure, an ext command, a layout, a record set, a file by its path, a game.toml value by its dotted key, a field an editing hook writes (hook.wildmon:level).

  • Two packages give or change the same named thing: a build error, naming both files and lines and the line to add to one package’s [overrides].
  • An override names the thing and the owner it replaces (another package, or engine for built-in content). Two packages overriding the same thing is again an error.
  • The game itself is the top layer: its files replace a package’s or the engine’s without a declaration, and the build report lists every such case.
  • Hooks chain. Several packages may hook the same event; only the fields they write are owned. The order is fixed: engine rules, then packages by dependency and name, then the game.

The result never depends on the order packages were added in.

Planned (plan 46): ploom build prints, and writes into build/report.json, what each package adds and overrides, the hooks in the order they run, and, for packages with Rust, their code size on DS. ploom check warns when an override has no scenario test that names it, so a changed rule is always tested by the game that changed it.

A package without Rust cannot run code on your machine. ploom reads its TOML, PBS, pictures and script source as data, and its scripts run only in the game’s script machine, which has no access to files, the network or the clock beyond the game’s own. At worst it makes a game behave badly, which its tests and the report show.

A package with Rust is code you run. Cargo compiles it, so its build scripts and procedural macros run on your machine with your rights, and its code runs inside the game on every player’s machine. Planned (plan 46), ploom guards against accidents and surprises:

  • ploom add prints, before copying, whether there is a crate, its dependencies, whether any has build code, and whether it uses unsafe, then asks to go on;
  • a package’s crate must be #![no_std] and free of unsafe unless it says so, which the report shows as a warning;
  • build code is refused unless you allow it for that package;
  • ploom update shows the changed files and asks again when a crate changed.

This is a guardrail, not a sandbox: allowing a crate means trusting its author.

Planned (plan 46): the engine’s own optional features made of data and scripts (the quest log, outfits, encounter information) ship inside ploom as built-in packages, turned on by their game.toml settings and layered like any other. ploom eject builtin:quests copies one into packages/ as your own, for changes deeper than its settings allow.

Planned (plan 46): a package’s crate builds for the desktop and the DS like a game’s own crate, against one engine facade crate, pl-ext. A crate that fails the DS build fails the whole build: there is no desktop-only package, because a PokeLoom game is one game on both platforms. How a game’s Rust is compiled in is on Rust extensions.

  • Shared logic goes in a shared script module of the game (scripts/), with procedures (Scripts and events).
  • A story played on other data, or in another project’s look, is made with ploom sync and an overlay folder (Creatures and data, Asset roles and style chains).
  • Editing hooks (on wildmon, on trainerparty, on givemon) already let a game’s scripts change a creature or a team before the engine uses it; packages will chain them.