Contributing
Getting started
Section titled “Getting started”Read these, in the repository, before changing the engine:
AGENTS.md: the hard rules and code conventions, summarised below.docs/plans/00-overview.md: architecture, constraints, budgets, crate layout.docs/decisions-current.md: the rules in force.- The plan in
docs/plans/for the area you touch, and its task files (docs/tasks/INDEX.mdlists them). - The module comment at the top of the crate’s
lib.rs.
This site describes the finished engine and marks what is built; the plans are where each design is argued.
Hard rules
Section titled “Hard rules”These are not traded against anything.
- No Nintendo assets or official creature data in the repository, including tests, fixtures and history. Identifiers are allowed: code and tests may name a move, ability, item or species by its ID. Data and content are not: stat tables, learnsets, descriptions, trainer teams, art, audio, maps, story text. Real data and pictures are fetched or imported on a creator’s own machine into git-ignored folders. Packs are built, never committed (why).
- Do not recreate an existing game. The sample game is original, and so are the tests’ fixtures.
- 4 MB of RAM on the DS is a hard limit. A change that breaks a budget is not done. Never drop content or ask creators to use a toolchain to save memory; optimise instead (budgets).
- One engine, two platforms. A feature is done when it works on desktop and in melonDS (testing).
- Built-in battle rules are checked against Pokémon Showdown, not memory. No built-in mechanic is done without a conformance or ported scenario test. A game may add or override mechanics, declared, reported by the build and covered by that game’s own tests (decision 230; custom mechanics).
- Installing software, using administrator rights, committing and pushing are agreed with the project’s owner first.
Reading other games: the clean room
Section titled “Reading other games: the clean room”Reference material (ROMs, Showdown’s sources, the community decompilations) lives in
external/, which git ignores. A decompilation may be read to learn how a game does
something (decision 200). What is learned is described in your own words and cited by
file and function in the task’s notes. Nothing is copied: no code, no tables, no
data, no text. A test fixture in a game’s format is written by hand, never taken
from a tree. Ported Showdown code keeps its attribution (Showdown is MIT-licensed).
Code conventions
Section titled “Code conventions”| Convention | Why |
|---|---|
Crates that run on the DS are #![no_std] with alloc |
The DS has no operating system |
No floating point in them; use Fx from pl-core |
No FPU; and the same result on every platform |
No core::fmt in hot or size-sensitive paths; user-visible text is string IDs |
Formatting costs tens of KB of code on the DS |
Logic is deterministic; all randomness through pl-core’s RNG |
Replays, tests, link battles and co-op depend on it (determinism) |
pl-battle, pl-world, pl-ui, pl-script, pl-systems never depend on a platform crate; only pl-game talks to pl-platform |
Logic tested on the host, the same on both platforms (architecture) |
| Static tables of plain functions over trait objects, closures and per-effect generics | Code size on the DS matters more than elegance |
| No per-frame heap allocation in the game loop | Fragmentation and time on a 4 MB machine |
| Tests first; logic tested on the host | Most bugs are caught in seconds, not in an emulator |
| No legacy code | A change replaces the old outright: no deprecated names, aliases, old-format readers or compatibility shims (decision 306) |
Feel and layout values (text speed, movement, camera, sizes) are named constants with
the measurement they came from (pl_world::feel, pl_ui::feel), never bare numbers.
Decisions
Section titled “Decisions”Every decision in the plans carries one of two marks:
- [user]: the owner decided it. It is fixed. To change it, ask the owner, with the reason and the options.
- [call]: an engineering call made by whoever wrote the plan. It may change with evidence: a measurement, a test, a reference that shows it wrong. Make the change and record it.
Examples: “the engine is in Rust” and “battle rules are checked against Showdown” are [user]; “the desktop renders in software” and “maps are edited in Tiled” are [call].
When a question needs the owner, it is asked as a multiple-choice question with a recommended option, batched with others, and only when the answer cannot be found by reading or measuring.
Decision log
Section titled “Decision log”docs/decisions.mdis the log: every owner answer and every change to a plan, numbered in order, never renumbered. A decision is cited by its number everywhere (“decision 204”). When a rule is replaced, the log keeps both entries.docs/decisions-current.mdis the digest: only the rules that stand, grouped by area (the repository, data, battle, overworld, formats, scripts, interface, audio, the importer, multiplayer), each with the chain of numbers that led to it (“[user] 158 → 180 → 187”). Read this one; go to the log for the history. When the two disagree, the log wins and the digest is wrong.- A test (
xtask/tests/docs.rs) refuses a number used twice or a gap, and requires the digest to name the log’s latest decision.
A change that alters a rule records the new decision in the log and updates the digest in the same change.
Registry
Section titled “Registry”Some numbers live in the code and in saved or built files: script hook kinds, save sections, bits of the game record’s flags, format versions, file magics, plan numbers, task letters. If two changes made at the same time each took “the next free number”, they would collide, and a save or pack written by one would be misread by the other.
So such numbers are given out in docs/registry.md before any code uses them.
The registry lists each number, its name and its state (in use, reserved,
retired: a retired number is never reused). xtask/tests/docs.rs checks the tables
marked “checked” against the code: a number in the code the registry did not give out,
or gave to another name, fails the tests.
Things found by name need no number and are not in the registry, because two changes adding them never collide:
| Thing | Named by |
|---|---|
| Engine strings | a key in pl_game::strings::KEYS; a constant is id("its_key") |
| Script commands and system calls | a row of pl_script::ops’s command table, appended |
test-nds sessions |
a row of xtask/src/sessions.rs, by its name |
| Pack sections | a four-letter tag in pl_data::tag |
Packs are always built with their runtime, so a command’s position is never stored anywhere that must stay stable.
Plans and tasks
Section titled “Plans and tasks”docs/plans/NN-*.mdare the designs, numbered from the registry. A plan states its decisions with their marks, its costs on the DS, its milestones and the evidence each needs.docs/tasks/holds a file per task (NNx-words.md): a checklist written before the work, then results with numbers (tests, sizes, measurements), what was not done and decisions to record.docs/tasks/INDEX.mdlists them.docs/PLAN.mdis the order of work; see the roadmap.
Evidence is counted, not judged: a milestone is done when its tests pass, its
test-nds sessions agree, its budgets hold and, for a change meant to look like an
original game, its pairs pass. “Looks right” is not evidence. Say plainly what was not
verified.
Documentation
Section titled “Documentation”- Generated references (the
game.toml,map.toml,world.tomlandlights.tomlkeys, and the script language) are written bycargo xtask blessfrom the code’s own tables. Edit the table, not the generated file. - This site lives in
website/and is the description of the finished engine. Each page opens with what is built and what is planned; update the status note when a planned feature lands, and remove its “Planned” mark where it is described.
Licence
Section titled “Licence”PokeLoom is under MIT OR Apache-2.0. Third-party work included under its own
licence is listed in CREDITS.md (for example the sample game’s creature pictures,
CC BY 4.0). Tests and code ported from Pokémon Showdown (MIT) keep their attribution.