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.
Contents
Section titled “Contents”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 projectversion = "1.2.0" # semantic versioningengine = ">=0.12, <0.14" # the ploom versions it builds withdescription = "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 defaultschain_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.
Commands
Section titled “Commands”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.
Conflicts
Section titled “Conflicts”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
enginefor 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.
Report
Section titled “Report”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 addprints, before copying, whether there is a crate, its dependencies, whether any has build code, and whether it usesunsafe, then asks to go on;- a package’s crate must be
#![no_std]and free ofunsafeunless it says so, which the report shows as a warning; - build code is refused unless you allow it for that package;
ploom updateshows the changed files and asks again when a crate changed.
This is a guardrail, not a sandbox: allowing a crate means trusting its author.
Built-in packages
Section titled “Built-in packages”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.
Until then
Section titled “Until then”- 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 syncand 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.