Skip to content

Contributing

Read these, in the repository, before changing the engine:

  1. AGENTS.md: the hard rules and code conventions, summarised below.
  2. docs/plans/00-overview.md: architecture, constraints, budgets, crate layout.
  3. docs/decisions-current.md: the rules in force.
  4. The plan in docs/plans/ for the area you touch, and its task files (docs/tasks/INDEX.md lists them).
  5. 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.

These are not traded against anything.

  1. 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).
  2. Do not recreate an existing game. The sample game is original, and so are the tests’ fixtures.
  3. 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).
  4. One engine, two platforms. A feature is done when it works on desktop and in melonDS (testing).
  5. 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).
  6. Installing software, using administrator rights, committing and pushing are agreed with the project’s owner first.

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

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.

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.

  • docs/decisions.md is 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.md is 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.

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.

  • docs/plans/NN-*.md are 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.md lists them.
  • docs/PLAN.md is 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.

  • Generated references (the game.toml, map.toml, world.toml and lights.toml keys, and the script language) are written by cargo xtask bless from 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.

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.