feat(mon): port the Gen1 recomp architecture to a PocketJS runtime on PSP

[doodlewind]

Ports bryanthaboi/pokemon-gen1-recomp-project — a 44 kLOC Lua/LÖVE2D recreation of a Gen 1 creature RPG — into the PocketJS ecosystem as its own specialized runtime, built on the Cores + Surfaces + Guest pattern in docs/RUNTIMES.md, and running on a PSP.

Rust and TypeScript only. No C anywhere in the tree.

The clean-room boundary

The upstream project is a shell: it ships no content and reconstructs graphics, maps, species tables, text and audio by decoding a player-supplied Game Boy ROM at first boot. This port has no counterpart to that layer — no ROM reader, no SHA-1 gate, no importer, no cache — and a test enforces it (tests/mon-content.test.ts, "the runtime has no path that reads a ROM").

What crosses over is mechanics: the damage formula, stat and growth curves, the encounter roll, the catch algorithm, the bottom-left-tile collision rule. Each ported rule keeps its provenance citation in the Rust source.

What ships instead is SPARKWOOD — original creatures, world, dialogue, art and music, authored in TypeScript, playable from a clean checkout.

What is here

engine/pocketmon/crates/pocketmon-core	The RPG core. Grid world with the bottom-left-tile rule and stitched map connections; a full turn-battle engine (damage/crit/accuracy, type chart, 30 move effects, status, catching, experience, trainer AI); a resumable 41-verb script VM; a four-voice chip synth; a checksummed binary save; text engine; scene builder; the mon surface dispatcher. no_std + alloc, zero dependencies, zero floating point.
engine/pocketmon/crates/pocketmon-gu	The sceGu backend for the core's draw list.
engine/pocketmon/crates/pocketmon-psp	The EBOOT: arena allocator, frame loop, input mapping, an audio thread, and a capture build.
engine/pocketmon/crates/pocketmon-sim	The headless host: same core, a reference software rasterizer, PNG and WAV output, and an intent-based tape format.
contracts/spec/mon-spec.ts	The surface, codegen'd to Rust with a byte-compare drift guard.
apps/mon	SPARKWOOD: content, procedural art, the score, the cooker, the guest SDK.

Verification

• 261 core tests — the formula matrix (crit / STAB / dual-type floors / the byte-overflow stat rule), roll distributions, growth curves inverted against their own thresholds, collision, seam round-trips, the script VM's blocking verbs, save corruption rejection, the synth's tuning (octaves double exactly, A4 lands on 440.000 Hz), and a fuzz that every battle terminates across 60 seeds.

• 36 contract + content tests — spec drift, and integrity checks that catch what is invisible on screen: a warp whose block has no door under it, a connection offset that is not mirrored, a species with no level-5 move, a character the font does not carry.

• bun tools/mon.ts check — a deterministic playthrough (out of the house → across the village → take a starter from the professor → north to Route One → win two wild battles) asserted against recorded frame hashes.

• bun tests/e2e/mon-ppsspp.ts — the same journey on the console. There is no second tape: pocketmon-sim --emit-psp replays the intent tape and writes out the per-frame input it produced, which the capture EBOOT replays verbatim. Sound only because the core is identical and deterministic on both hosts — the runtime's premise, cashed in.

  Asserts three things: liveness (14/14 checkpoints, 2877 frames, boot through two won battles), byte-exact PNG goldens, and backend agreement — every checkpoint compared pixel for pixel against the software rasterizer's own output. All 14 agree exactly.

• The repo's existing suite: 462 tests, unchanged.

Not done

Stated plainly in docs/MON.md §2 rather than implied away:

• No QuickJS realm is mounted in the EBOOT. TypeScript here is ahead-of-time compiled rather than interpreted — the vapor/ precedent, not the hosts/psp one — which is what keeps the whole runtime to Rust + TypeScript with no C in the tree. The mon surface is specified and implemented (Game::op, one dispatcher, covered by cargo test) with a guest SDK in apps/mon/sdk.ts, so mounting a realm later is a thin binding over an existing boundary. A decision left open, not an oversight.
• Real hardware is untested. Emulator only so far.
• Link play, the save editor and the mod-manager UI are out of scope for v1.

Four bugs worth calling out

All found by a harness and fixed at the source, not worked around:

• Events re-dispatched every tick. The core reacts to some of its own facts (an encounter starts a battle, a talk starts a script) while the guest drains the same batch. Without a watermark it re-handled every event for as long as the batch sat undrained — which reopened a conversation the moment you closed it, forever.
• A 14-byte GE vertex. #[repr(C, packed)] gives a 14-byte textured vertex; the GE pads to 16. It does not crash — it draws a screen of plausible-looking garbage, because every vertex after the first reads two bytes into its predecessor. Now a const assertion.
• The frame a script ends was a frame you could act on. A script's last instruction runs in the same frame as the button press that released it, so closing a conversation with A immediately reopened it. The world gate now reads the script state from the top of the frame.
• The audio mix peaked at 0.3% of full scale, having been gain-staged as though the output were 8-bit. Every unit test passed, because they all asserted "not silent" rather than "audible". They now assert a floor, and bun tools/mon.ts audio renders the score to WAV so a human can check the tune.

🤖 Generated with Claude Code