romdevtools 0.43.0 → 0.56.1

package/CHANGELOG.md

@@ -4,6 +4,328 @@ All notable changes to `romdevtools`. Dates are release dates.
 (Published as `romdev-mcp` through 0.11.0; renamed to `romdevtools` in 0.13.0 —
 the `romdev-mcp` bin is kept as an alias.)
 
+## 0.56.1 — 2026-06-26
+
+### ascii screenshot: legible default grid + lighter default color (0.44.0 feedback #1)
+
+`frame({op:'screenshot', format:'ascii'})` defaulted to a `fb/16` grid (16×14 for a
+256×224 NES frame — too coarse to read any game state) AND truecolor (`38;2;r;g;b`
+per cell, ~7.9KB of escapes). So the "cheap text screenshot" was both expensive and
+useless for an "are we in gameplay?" check.
+
+- default grid is now `fb/8` (one cell per 8×8 tile → 32×28 for NES, legible).
+- default `colors` is now `'256'` (indexed) instead of `'true'` — near-identical read,
+  far fewer escape bytes. Net for the NES case: 4× more cells AND ~55% smaller
+  (7876B → 3551B).
+- when a caller forces a grid too coarse to show state, the result carries a `note`
+  pointing at `memory({op:'read'})` as the cheaper exact path for a pass/fail check.
+
+## 0.56.0 — 2026-06-26
+
+### N64 + PS1 are now SHIPPABLE: core packages + toolchain wired for publish
+
+The functionality was done, but the artifacts weren't distributable — the cores lived
+only in the gitignored dev-staging dir, with no npm package to publish. Fixed:
+
+- **New `romdev-core-pcsx-rearmed`** (PS1) and **`romdev-core-parallel-n64`** (N64,
+  headless-angrylion software) packages, mirroring the 14's structure (package.json
+  + index.js + README + gitignored `wasm/` shipped via the `files` allowlist +
+  verify-wasm prepublish guard). These are CUSTOM romdev builds (the romdev debug
+  exports + IPL3) — documented in each README + built by scripts/build-*.sh.
+- **`romdev-toolchain-mips-gcc`** moved to required `dependencies` (build needs it);
+  the two cores added to `dependencies` (always installed, like the 14). lockfile
+  regenerated — `npm ci` passes.
+- publish-all.mjs now discovers all 3 (26 packages total).
+
+### A real shipping bug the npm-pack smoke test caught
+
+The cores' Emscripten glue had a DEV SCRATCH wasm name baked in (`pcsx_vram.wasm`,
+`pn64_sw.wasm` from `-o $SCRATCH/...`) instead of the published `*_libretro.wasm`.
+The host always passes `wasmBinary` so it worked in dev — but any consumer loading
+the factory directly got ENOENT. Re-linked both glues with the correct `-o` name (the
+build scripts already used it; only my hand-links were wrong). A clean-install smoke
+test (npm pack → install into a bare dir → resolve + instantiate + check exports) +
+a packaging contract test now pin this so it can't silently regress.
+
+Verified: clean-install smoke test passes, full build→load-from-package→run→render
+pipeline works for both, npm ci + lint + 1054/1054 tests green. Ready for `npm publish`.
+
+## 0.55.0 — 2026-06-26
+
+### System manifests now call out the features a platform CAN'T have (and why)
+
+A bare `inspectSprites: false` in the capability manifest is ambiguous — an agent
+can't tell "N/A by hardware, permanent" from "a decoder we haven't built." For the
+14 tile-based systems this never bit (they support those ops); for the framebuffer
+(PS1) / 3D (N64) systems, FOUR ops are false with no stated reason.
+
+- New `naReason(platform, op)` in the capability manifest returns a HARDWARE-grounded
+  explanation, keyed on `renderingKind`: a framebuffer/3D renderer has no tile/
+  sprite-attribute/nametable/palette tables for the tile-era inspectors to read —
+  those ops are *meaningless on the hardware*, not merely absent. (PS1 `cart` →
+  "disc-based, no cartridge ROM".)
+- `platform({op:'capabilities', platform})` now includes a `naReasons` map alongside
+  `ops`, so the manifest itself states what each platform can't do + why.
+- The `unsupported()` signal from inspectSprites/inspectPalette/inspectBackground/
+  renderingContext now carries that hardware reason instead of a generic "no decoder
+  for this platform" — an agent gets "this is a 3D renderer, there are no sprite
+  tables" and won't retry or request a decoder that can't exist.
+- Conformance test pins it: every false introspection op on ps1/n64 must carry a
+  hardware-grounded N/A reason. Suite 1054/1054.
+
+## 0.54.0 — 2026-06-26
+
+### Audit: two real N64/PS1 parity gaps found + fixed
+
+A full per-tool audit (all 32 tools, live-probed on both platforms) surfaced two
+genuine gaps where the platform was CAPABLE but the tool didn't deliver:
+
+1. **PS1 reverse-engineering returned bogus addresses.** `disasm`/`cfg`/`xrefs`/
+   `functions`/`decompile` on a PS1 PS-EXE found a single fake `fcn.00000000` at
+   file offset 0 (not the real 0x80010000+ VA), and `decompile` then threw "address
+   maps outside the image." Root cause: rizin ignores `-B` on a raw buffer, so the
+   stripped .text was analyzed flat from 0, and PS1's ABSOLUTE jal targets dangled →
+   no cross-function discovery. Fix: left-pad the .text so flat offset == the VA's
+   low 20 bits (jal-following now works) and add the high bits back as a rebase, so
+   every reported address is a real VA that round-trips. PS1 now finds all functions
+   (16 vs 1) at correct VAs, CFG/xrefs/decompile all resolve. (N64 was already fine.)
+
+2. **PS1 `video_ram` was claimed but empty.** The manifest lists `video_ram` for
+   every platform, but pcsx_rearmed never exposed the GPU VRAM. Added a
+   `romdev_vram_get` export (1024×512×16bpp) wired into `memory({region:'video_ram'})`
+   — PS1 GPU VRAM is now readable (verified: rendered pixels show up).
+
+Everything else in the audit was already at parity or genuinely N/A-by-hardware
+(the tile/sprite/nametable/palette inspectors need tables a framebuffer/3D renderer
+doesn't have; `cart` is for cartridge ROMs). save/loadState, runUntil, frame-verify,
+romPatch, and the agnostic art/snippet tools all work on both. Suite 1053/1053.
+
+## 0.53.0 — 2026-06-26
+
+### N64 + PS1 reach EXAMPLE parity: 5 full genre games each
+
+Both new platforms now ship the same caliber of bundled, playable examples as the
+other 14 (parity = "5 decent full games"), registered in project.js and forkable +
+buildable through the normal createProject/build tool flow.
+
+**PS1** (4 × 3D + 1 × 2D, on a software 3D engine + the GPU): shmup STARFALL,
+racing POLE BENDER (a real receding 3D road), platformer BLOCK HOP, sports
+SLAM COURT (3D pong/air-hockey), puzzle DROP GRID (2D — the right idiom for a grid).
+
+**N64** (all 5 × 3D — the N64 was a 3D-first machine, so even the puzzle is a 3D
+well of cubes): STARFALL 64 / POLE BENDER 64 / BLOCK HOP 64 / SLAM COURT 64 /
+DROP GRID 64, on the same software-3D lib with a framebuffer backend the
+headless-angrylion core scans out.
+
+Every example builds + boots + renders, verified on the actual cores (frames
+inspected). The N64 path required the three earlier breakthroughs (self-booting
+.z64 via a clean IPL3, a headless-angrylion GL-free core, and the VI-scanout
+software rasterizer). Suite 1052/1052.
+
+**This completes N64 + PS1 parity** — every tool the other 14 have works, and both
+ship 5 full idiomatic examples.
+
+## 0.51.0 — 2026-06-26
+
+### N64 audioDebug — FULL parity (zero functional gaps)
+
+- **`getAudioState({chip:'ai'})`** decodes the N64 Audio Interface: sample rate
+  (from DACRATE + the VI clock), whether audio is playing (a buffer is DMA-queued),
+  the DMA source address. (N64 audio is RSP-mixed, so the AI is the OUTPUT state, not
+  per-voice — that lives in game-specific RSP audio lists in RDRAM.) Verified: a real
+  ROM reports `playing:true, sampleRate:32006`. From a `romdev_ai_get` export added
+  to parallel_n64. n64 `audioChips:['ai']`, `audioDebug:true`.
+
+**This closes the last functional gap.** A programmatic audit confirms N64/PS1 now
+match the canonical 14 on every applicable op — build, run, screenshot, memory,
+cpuState, audioDebug, disasm, decompile, cheats, breakpoint, watch. The only manifest
+differences are N/A BY HARDWARE: the tile/sprite/nametable/palette inspectors
+(framebuffer/3D renderers have no such tables) and `cart` (disc-based). Suite 1052/1052.
+
+## 0.50.0 — 2026-06-26
+
+### PS1 SPU audioDebug
+
+- **`getAudioState({chip:'spu'})`** decodes the PS1 SPU's 24 ADPCM voices (per-voice
+  volume L/R, pitch→Hz, ADSR, key-on/off + main volume + control), from a
+  `romdev_spu_get` export added to pcsx_rearmed (copies the SPU regArea). Verified:
+  a toolchain-built program's SPU register writes read back correctly.
+- ps1 `audioDebug:true` in the manifest.
+
+**Parity status (N64/PS1 vs the canonical 14):** at parity on build, run, screenshot,
+memory, cpuState, disasm, decompile, cheats, breakpoint, watch (+ PS1 audioDebug).
+Genuinely N/A by hardware: the tile/sprite/nametable/palette inspectors (framebuffer/3D
+renderers have no such tables) and `cart` (disc-based). **Remaining real TODO:** N64
+audioDebug (the RSP/AI audio path — a deeper decode than the PS1 SPU register block).
+
+## 0.49.0 — 2026-06-26
+
+### N64 + PS1 live-debug — breakpoint + watch now work
+
+The remaining big parity gap: the live-debugging RE tools. parallel_n64 (R4300) and
+pcsx_rearmed (R3000) are rebuilt with romdev's CPU instrumentation, so:
+
+- **`breakpoint({on:'pc'|'write'|'read'})`** + **`watch({on:'range'|'mem'})`** work on
+  both MIPS platforms — verified live: a C program (built by the romdev toolchain)
+  writing to a known address is caught by a write watchpoint with the writing PC, and
+  a range watch captures the write stream during emulation.
+- A `romdev_debug.c` instrumentation unit (per core) hooks the memory write/read paths
+  (write/read watch + range watch + coverage) and the interpreter step (PC break +
+  single-step). Exports the full `romdev_watchpoint`/`readwatch`/`pcbreak`/`range`/`cov`/
+  `regsnap`/`watchdog` set the host already expects — so the host needed ZERO changes
+  (its debug methods were already generic).
+- Reproducible via the updated build-pcsx-rearmed.sh / build-parallel-n64.sh
+  (patch the source + hooks + exports).
+
+**Remaining honest gap:** `audioDebug` (PS1 SPU / N64 audio chip decoders) is still
+TODO. The tile/sprite/nametable inspectors stay N/A by hardware (framebuffer/3D
+renderers have no such tables). Everything else is at parity. Suite 1050/1050.
+
+## 0.48.0 — 2026-06-25
+
+### N64 + PS1 `build` op — full feature parity
+
+The last missing op. N64 and PS1 now **build** C from source, completing parity
+with the 14 (every op: build, run, screenshot, memory, disasm, decompile, cheats,
+cpuState).
+
+- **A from-scratch `mips-elf` GCC toolchain compiled to WASM** — binutils 2.42 +
+  gcc 14.2.0 + newlib 4.4.0, the same two-stage pipeline as the Genesis m68k
+  toolchain. STAGE 1 builds it natively; STAGE 2 re-compiles cc1/as/ld/objcopy/
+  objdump to WASM. One toolchain serves both endiannesses (cc1 `-mel`/`-meb`,
+  as/ld `-EL`/`-EB`).
+- **`buildSource({platform:'ps1'|'n64', language:'c'})`** — cc1 → as → ld → objcopy,
+  links a minimal crt0 + libc/libm/libgcc. PS1 wraps the image in a PS-EXE the HLE
+  BIOS loads; N64 emits a big-endian flat image. **Verified end-to-end:** a C program
+  compiled by the toolchain boots and renders on the PS1 core (GPU fill executed).
+- Four GCC-15/emscripten build incompatibilities fixed along the way (all in the
+  build scripts): binutils `static_assert`-as-identifier (`-std=gnu11`), newlib
+  libgloss pre-C23 idioms (permissive target CFLAGS), libiberty `psignal` conflict
+  (source patch, both gcc + binutils copies), and the `all-gcc`/`all` aux-tool
+  targets pulling in ftw/gprofng (build the specific `cc1`/`as`/`ld` targets).
+- New `romdev-toolchain-mips-gcc` package (the WASM tools); pinned + reproducible
+  via `build-mips-toolchain.sh` + `build-mips-wasm-tools.sh`.
+
+**Caveats:** the bare build path has no SDK yet — PS1 is "drive the GPU/SPU
+registers yourself" (PSn00bSDK forthcoming); N64 compiles+links but a self-booting
+cart needs IPL3 + a libdragon header (libdragon forthcoming). Both are logic/RE-
+complete and the foundation for the SDKs. The framebuffer/3D renderers have no
+tile/sprite inspectors by nature.
+
+## 0.47.0 — 2026-06-25
+
+### N64 + PS1 reach feature parity (cheats + cpuState + decompile)
+
+The MIPS tier now matches the 14 on everything except `build`:
+
+- **MIPS decompile** — `disasm({platform:'n64'|'ps1', target:'decompile'})` produces
+  real Ghidra C pseudocode. **No Python**: the stock Ghidra MIPS SLEIGH spec is
+  compiled to `.sla` (MIPS:BE:32 for N64, MIPS:LE:32 for PS1) by the same
+  `sleigh_opt` that builds the other 8 CPU tables. (m2c/Pyodide was rejected — it
+  would drag a CPython runtime into the tool.)
+- **cpuState** — `cpu({op:'read'})` decodes the live R4300 (N64) / R3000 (PS1)
+  register file: 32 GPRs by o32 ABI name + lo/hi + PC. Backed by a tiny
+  `romdev_mips_regs_get` appended to each core's `libretro.c` (the new
+  `build-parallel-n64.sh` / `build-pcsx-rearmed.sh` recipes).
+- **cheats** — `_retro_cheat_set`/`_retro_cheat_reset` are now exported from the
+  rebuilt cores (they were in the upstream C, just unexported).
+- The cores are reproducible: pinned in `versions.json`, built by the new recipes
+  (clone → append the regsnap → emcc with the cheat+regsnap exports; the regsnap is
+  `EMSCRIPTEN_KEEPALIVE` so LTO doesn't strip it).
+
+**Parity scorecard** — N64 & PS1 now have: run, screenshot, memory r/w, disasm
+(cfg/xrefs/functions), decompile, cheats, cpuState. The one remaining op is
+**build** (a MIPS GCC→WASM toolchain — PSn00bSDK/libdragon — the largest separate
+piece). The framebuffer/3D renderers have no tile/sprite/nametable inspectors by
+nature.
+
+## 0.46.0 — 2026-06-25
+
+### N64 + PS1 run-side: boot, run, render (the MIPS tier goes live)
+
+Past analysis-only — N64 and PS1 now **boot, run, and present real frames** through
+the host. The 32-bit MIPS tier is a new partial tier (`tier:"mips"`), distinct from
+the canonical 14.
+
+- **N64** (ParaLLEl-N64, HW 3D render) — `run` + `frame({op:'screenshot'})` produce
+  real 3D frames headlessly via a GL framebuffer readback. Rendering goes through a
+  ported GL bridge (`LibretroGL`/`LibretroGLBridge`) backed by `native-gles` +
+  `webgl-node`, which are **optionalDependencies**: lazy-loaded only when an N64/PS1
+  core boots, so the 14 software platforms and headless installs without the GPU
+  module are completely unaffected (clear install hint if absent).
+- **PS1** (PCSX-ReARMed, software + **built-in HLE BIOS**) — `run` + screenshot with
+  zero firmware to ship, no GL dependency. Loads PS-EXE (and disc images).
+- **Memory** works for both: `readMemory`/`writeMemory` on `system_ram` (N64 = 8MB
+  RDRAM, PS1 = 2MB main RAM) — poke values directly.
+- **Static RE** (from 0.45.0) still works: `disasm({platform:'n64'|'ps1',
+  target:'rom'|'functions'|'cfg'|'xrefs'})`.
+- N64 `.v64`/`.n64` byte orders auto-normalize to `.z64`; PS-EXE headers are stripped.
+
+Three GL-binding bugs fixed to get frames on screen: the Emscripten `getContext`
+shim's `instanceof WebGLRenderingContext` check (needs WebGL1 to be a distinct
+class), the signed-vs-unsigned `RETRO_HW_FRAME_BUFFER_VALID` compare, and the
+all-transparent FBO alpha (forced opaque in a new RGBA decode path).
+
+**Still pending** for full parity (honestly off in the manifest): `build` (needs a
+MIPS toolchain — PSn00bSDK/libdragon), `decompile` (needs a MIPS SLEIGH spec in the
+decompiler — slaspec sources exist, a decompiler-package rebuild), `getCPUState` +
+`cheats` (need a core rebuild exposing those exports). The framebuffer/3D renderers
+have no tile/sprite/nametable inspectors by nature.
+
+## 0.45.0 — 2026-06-25
+
+### PS1 + N64 analysis-first (the 32-bit MIPS tier)
+
+The first step past the GBA-era line: static RE for PlayStation (R3000) and
+Nintendo 64 (R4300), via the MIPS plugin already in the shipped `rizin.wasm` — no
+new core, no toolchain, no GPU bridge in this slice.
+
+- **`disasm({platform:'ps1'|'n64', target:'functions'|'cfg'|'xrefs'|'rom'})`** —
+  works on real ROMs. Verified: a libdragon N64 homebrew (`FlappyBird.z64`)
+  recovers 251 functions with control-flow graphs and cross-references. The raw
+  N64 ROM has no entry `aaa` recognizes, so MIPS analysis is seeded at the
+  post-IPL3 code start (`af` + `aac`) — `aaa` finds 0, the seed finds the tree.
+- **Endianness is wired right:** PS1 is little-endian, N64 is big-endian (same
+  `mips` arch). N64 `.v64`/`.n64` dumps are auto-normalized to `.z64` byte order;
+  PS1 PS-EXE headers are stripped to the load address.
+- **Capability manifest:** `ps1` (framebuffer) / `n64` (3d) are an analysis-only
+  tier — `disasm` true; run-side ops (build/run/screenshot/the tile/sprite
+  inspectors) and `decompile` false. The tile/nametable inspectors are meaningless
+  on a framebuffer/3D renderer, so an agent gets the clean `unsupported()` signal.
+- **`decompile` (C pseudocode) is NOT available yet** for MIPS — the rz-ghidra
+  decompiler ships no MIPS SLEIGH spec (adding `MIPS.sla` is a later
+  `romdev-analysis-decompiler` rebuild). It returns a clear steer to the working
+  disasm targets, not a cryptic failure.
+
+## 0.44.0 — 2026-06-25
+
+### v0.41.0 feedback (part 2) — RE-session ergonomics
+
+- **`watch({on:'range'})` dedupe + digest.** A range watch over a churny window
+  flooded with per-frame writes (a counter inc'd at one PC → hundreds of
+  near-identical rows). New `dedupe:true` collapses identical `(pc,address,value)`
+  events to one row with an `occurrences` count (parity with `on:'dma'`), and
+  `distinctPCsOnly:true` returns JUST the per-PC digest (`byPC[{pc,count,
+  sampleAddress,sampleValue}]`) and suppresses the raw event list — the
+  token-cheap "which routines touch this range?" answer. (133737 N1)
+- **`catalog({op:'status'}).capabilities` build-toolchain flags.** Added
+  `cc65Build`, `ld65Link`, `da65Disasm` so an agent knows before calling
+  `build`/`disasm` whether the toolchain is present (the analysis subtargets
+  cfg/xrefs/functions/decompile are all da65-backed). (184553 #1, 190223 #1)
+- **`cheats` slot lifecycle.** `apply` now REPLACES an active freeze on the same
+  address instead of stacking a second one that fights for the byte
+  (`replacedSameAddress`), and new `op:'remove'` drops ONE cheat by slot/code
+  without `clear`'s nuke-all. (213831 #3)
+- **`breakpoint` `settleFrames`.** Back-to-back driven runs on the same live host
+  could inherit the prior run's held-button shadow on frame 0 (false-positiving a
+  negative control). `settleFrames:N` releases the pad to neutral and steps N
+  frames before the run so it starts clean. (213831 #1)
+- **`breakpoint({on:'pc'})` miss-note** now names the negative-control case: a
+  `hit:false` may be the DESIRED result (proving input X does NOT reach a branch),
+  not a wrong-address failure. (213831 #2)
+- Confirmed already shipped (0.42.0): hex-string `address`/`offset` params, the
+  base capabilities map. (133737 N2, 002129 #2)
+
 ## 0.43.0 — 2026-06-25
 
 ### Port engine is now GENERIC (any source → any target), not NES→SNES-only

package/examples/n64/platformer/main.c

@@ -0,0 +1,158 @@
+/*
+ * platformer/main.c — BLOCK HOP: a 3D Nintendo 64 platformer.
+ *
+ * A 3D character (cube hero) runs and jumps across floating platforms rendered in
+ * perspective. Gravity + jump physics in 16.16 fixed point, AABB landing tests
+ * against platform tops, coins to collect, a pit you can fall into (lose a life),
+ * a chase camera that follows the hero. Title -> play -> game-over, score + lives.
+ *
+ * Build: build({ platform:"n64", language:"c" }). Controls: LEFT/RIGHT run,
+ * CROSS jump, START begin/restart.
+ *
+ * 3D technique: platforms are flat-topped boxes drawn as no-cull quads; the hero
+ * is a culled cube. The camera tracks the hero's X with a slight downward tilt so
+ * you see the platform tops. Coins are small spinning cubes.
+ */
+#include "n64.h"
+
+#define NPLAT 6
+#define NCOIN 6
+enum { TITLE, PLAY, OVER };
+
+typedef struct { fix x, y, z, w; } Plat;   /* top-center + half-width */
+static Plat plat[NPLAT];
+static struct { fix x, y, z; int got; } coin[NCOIN];
+
+static fix hx, hy, vy;       /* hero pos + vertical velocity */
+static int onground;
+static int state, score, lives, hi;
+static fix cam_x, spin;
+static unsigned int prev_pad;
+
+static void box_top(fix cx, fix top, fix z, fix hw, fix depth, unsigned short col)
+{
+    Vec3 a,b,c,d;
+    a.x=cx-hw; a.y=top; a.z=z-depth; b.x=cx+hw; b.y=top; b.z=z-depth;
+    c.x=cx+hw; c.y=top; c.z=z+depth; d.x=cx-hw; d.y=top; d.z=z+depth;
+    n64_quad3d_nc(a,b,c,d,col);                       /* top face */
+    /* front face for thickness */
+    a.y=top; b.y=top; c.y=top-FIX(2); d.y=top-FIX(2);
+    a.x=cx-hw; a.z=z+depth; b.x=cx+hw; b.z=z+depth; c.x=cx+hw; c.z=z+depth; d.x=cx-hw; d.z=z+depth;
+    n64_quad3d_nc(a,b,c,d, col - RGB(20,20,20));
+}
+
+static void draw_cube_at(fix x, fix y, fix z, fix s, fix yaw, unsigned short col)
+{
+    Vec3 v[8]; int i;
+    static const int sx[8]={-1,1,1,-1,-1,1,1,-1},sy[8]={-1,-1,1,1,-1,-1,1,1},sz[8]={-1,-1,-1,-1,1,1,1,1};
+    n64_model(x,y,z,yaw);
+    for(i=0;i<8;i++){v[i].x=sx[i]*s;v[i].y=sy[i]*s;v[i].z=sz[i]*s;}
+    n64_quad3d(v[0],v[1],v[2],v[3],col); n64_quad3d(v[5],v[4],v[7],v[6],col);
+    n64_quad3d(v[4],v[0],v[3],v[7],col); n64_quad3d(v[1],v[5],v[6],v[2],col);
+    n64_quad3d(v[4],v[5],v[1],v[0],col); n64_quad3d(v[3],v[2],v[6],v[7],col);
+}
+
+static void reset_game(void)
+{
+    int i;
+    /* a run of platforms along +X with a gap (pit) in the middle */
+    for (i = 0; i < NPLAT; i++) {
+        plat[i].x = (fix)(i * 4 - 4) << 16;
+        plat[i].y = (fix)((i % 3) - 1) << 16;
+        plat[i].z = FIX(8);
+        plat[i].w = FIX(2);
+    }
+    plat[3].y = FIX(-6);          /* the pit: a platform dropped far below */
+    for (i = 0; i < NCOIN; i++) { coin[i].x = (fix)(i*4-3)<<16; coin[i].y = plat[i].y + FIX(2); coin[i].z = FIX(8); coin[i].got = 0; }
+    hx = FIX(-4); hy = FIX(2); vy = 0; onground = 0;
+    score = 0; lives = 3;
+}
+
+/* find the platform top under the hero's x (or a very low floor = pit). */
+static fix ground_at(fix x)
+{
+    int i; fix best = FIX(-20);
+    for (i = 0; i < NPLAT; i++) {
+        fix dx = x - plat[i].x; if (dx < 0) dx = -dx;
+        if (dx < plat[i].w) { if (plat[i].y > best) best = plat[i].y; }
+    }
+    return best;
+}
+
+static void update(void)
+{
+    unsigned int pad = n64_pad();
+    int i;
+    if (pad & PAD_LEFT)  hx -= FIXF(0.18f);
+    if (pad & PAD_RIGHT) hx += FIXF(0.18f);
+    if (hx < FIX(-6)) hx = FIX(-6); if (hx > FIX(14)) hx = FIX(14);
+
+    if ((pad & PAD_A) && !(prev_pad & PAD_A) && onground) { vy = FIXF(0.55f); onground = 0; }
+
+    vy -= FIXF(0.04f);            /* gravity */
+    hy += vy;
+    {
+        fix g = ground_at(hx) + FIX(1);  /* hero sits 1 unit above the platform top */
+        if (hy <= g && vy <= 0) {
+            if (g < FIX(-8)) { /* fell in the pit */
+                if (--lives <= 0) { if (score>hi) hi=score; state = OVER; }
+                hx = FIX(-4); hy = FIX(4); vy = 0;
+            } else { hy = g; vy = 0; onground = 1; }
+        } else onground = 0;
+    }
+
+    for (i = 0; i < NCOIN; i++) if (!coin[i].got) {
+        fix dx = hx - coin[i].x, dy = hy - coin[i].y;
+        if (dx<0)dx=-dx; if (dy<0)dy=-dy;
+        if (dx < FIX(1) && dy < FIX(2)) { coin[i].got = 1; score += 100; }
+    }
+
+    cam_x += (hx - cam_x) >> 3;   /* smooth follow */
+    spin += FIX(4);
+    prev_pad = pad;
+}
+
+static void render(void)
+{
+    int i;
+    n64_clear(RGB(40, 60, 120));   /* sky */
+    n64_camera(cam_x, FIX(2), FIX(-1), 0, FIXF(-0.22f));
+
+    for (i = 0; i < NPLAT; i++)
+        box_top(plat[i].x, plat[i].y, plat[i].z, plat[i].w, FIX(2),
+                (i==3)?RGB(120,40,40):RGB(90, 150, 70));
+    for (i = 0; i < NCOIN; i++) if (!coin[i].got)
+        draw_cube_at(coin[i].x, coin[i].y, coin[i].z, FIXF(0.3f), spin, RGB(255, 220, 40));
+
+    draw_cube_at(hx, hy, FIX(8), FIXF(0.6f), 0, RGB(230, 90, 60));
+
+    n64_number(8, 6, (unsigned)score, RGB(255,255,255));
+    for (i = 0; i < lives; i++) n64_rect(290 - i*10, 8, 6, 6, RGB(230, 90, 60));
+}
+
+int main(void)
+{
+    n64_init();
+    n64_srand(0xBEEF);
+    state = TITLE; prev_pad = 0; cam_x = 0;
+    for (;;) {
+        unsigned int pad = n64_pad();
+        if (state == TITLE) {
+            n64_clear(RGB(20, 30, 60));
+            n64_camera(0, 0, FIX(-1), 0, 0);
+            spin += FIX(3);
+            draw_cube_at(0, 0, FIX(6), FIX(1), spin, RGB(230, 90, 60));
+            if ((pad & PAD_START) && !(prev_pad & PAD_START)) { reset_game(); state = PLAY; }
+            prev_pad = pad;
+        } else if (state == PLAY) { update(); render(); }
+        else {
+            n64_clear(RGB(8, 8, 30));
+            n64_number(110, 100, (unsigned)score, RGB(255, 220, 40));
+            n64_number(120, 130, (unsigned)hi, RGB(255, 255, 120));
+            if ((pad & PAD_START) && !(prev_pad & PAD_START)) { reset_game(); state = PLAY; }
+            prev_pad = pad;
+        }
+        n64_flip();
+    }
+    return 0;
+}

package/examples/n64/puzzle/main.c

@@ -0,0 +1,117 @@
+/*
+ * puzzle/main.c — DROP GRID 64: a 3D Nintendo 64 falling-block puzzle.
+ *
+ * Unlike the PS1 puzzle (flat 2D), this is rendered in 3D — the N64 was a 3D-first
+ * machine, so the well is a perspective box and the blocks are shaded cubes you
+ * watch fall in depth. Same falling-block logic (move, drop, clear full rows, ramp
+ * speed, stack-out = game over) but presented through the 3D pipeline at an angle.
+ *
+ * Build: build({ platform:"n64", language:"c" }). Controls: LEFT/RIGHT move the
+ * falling block, DOWN soft-drop, START begin/restart.
+ *
+ * 3D technique: each grid cell is a cube at (col, -row, 0) in world space; a tilted
+ * camera looks into the well so you see depth. The board logic is plain integers.
+ */
+#include "n64.h"
+
+#define GW 6
+#define GH 10
+enum { TITLE, PLAY, OVER };
+
+static unsigned char grid[GH][GW];
+static int fx, fy, fc;
+static int tick, fall_period;
+static int state, score, hi;
+static unsigned int prev_pad;
+
+static const unsigned short PAL[5] = {
+    0, RGB(230,60,60), RGB(60,200,90), RGB(80,150,255), RGB(240,200,60)
+};
+
+static void cube_at(fix x, fix y, fix z, fix s, unsigned short col)
+{
+    Vec3 v[8]; int i;
+    static const int sx[8]={-1,1,1,-1,-1,1,1,-1},sy[8]={-1,-1,1,1,-1,-1,1,1},sz[8]={-1,-1,-1,-1,1,1,1,1};
+    n64_model(x,y,z,0);
+    for(i=0;i<8;i++){v[i].x=sx[i]*s;v[i].y=sy[i]*s;v[i].z=sz[i]*s;}
+    n64_quad3d(v[0],v[1],v[2],v[3],col); n64_quad3d(v[5],v[4],v[7],v[6],col);
+    n64_quad3d(v[4],v[0],v[3],v[7],col); n64_quad3d(v[1],v[5],v[6],v[2],col);
+    n64_quad3d(v[4],v[5],v[1],v[0],col); n64_quad3d(v[3],v[2],v[6],v[7],col);
+}
+
+/* grid cell (c,r) → world position (centered, y up). */
+static fix cellx(int c) { return (fix)(c - GW/2) << 16; }
+static fix celly(int r) { return (fix)((GH/2) - r) << 16; }
+
+static void new_block(void)
+{ fx=GW/2; fy=0; fc=1+(n64_rand()%4); if(grid[0][fx]){ if(score>hi)hi=score; state=OVER; } }
+
+static void reset_game(void)
+{ int r,c; for(r=0;r<GH;r++)for(c=0;c<GW;c++)grid[r][c]=0; score=0; tick=0; fall_period=30; new_block(); }
+
+static int blocked(int x,int y){ return x<0||x>=GW||y>=GH||(y>=0&&grid[y][x]); }
+
+static void lock_and_clear(void)
+{
+    int r,c,rr;
+    grid[fy][fx]=fc;
+    for(r=GH-1;r>=0;r--){
+        int full=1; for(c=0;c<GW;c++) if(!grid[r][c]){ full=0; break; }
+        if(full){ for(rr=r;rr>0;rr--)for(c=0;c<GW;c++)grid[rr][c]=grid[rr-1][c]; for(c=0;c<GW;c++)grid[0][c]=0; score+=100; if(fall_period>8)fall_period--; r++; }
+    }
+    new_block();
+}
+static void step_fall(void){ if(!blocked(fx,fy+1)) fy++; else lock_and_clear(); }
+
+static void update(void)
+{
+    unsigned int pad = n64_pad();
+    if((pad&PAD_LEFT)&&!(prev_pad&PAD_LEFT)&&!blocked(fx-1,fy)) fx--;
+    if((pad&PAD_RIGHT)&&!(prev_pad&PAD_RIGHT)&&!blocked(fx+1,fy)) fx++;
+    if(pad&PAD_DOWN){ step_fall(); tick=0; }
+    if(++tick>=fall_period){ step_fall(); tick=0; }
+    prev_pad=pad;
+}
+
+static void render(void)
+{
+    int r,c;
+    n64_clear(RGB(12,12,24));
+    n64_camera(0,0,FIX(-12),0,FIXF(-0.05f));   /* look into the well */
+    /* settled blocks */
+    for(r=0;r<GH;r++) for(c=0;c<GW;c++) if(grid[r][c])
+        cube_at(cellx(c), celly(r), 0, FIXF(0.45f), PAL[grid[r][c]]);
+    /* falling block */
+    if(fy>=0) cube_at(cellx(fx), celly(fy), 0, FIXF(0.45f), PAL[fc]);
+    /* well floor + walls as dim cubes for depth cue */
+    for(c=-1;c<=GW;c++){ cube_at(cellx(c), celly(GH), 0, FIXF(0.45f), RGB(50,50,70)); }
+    for(r=0;r<=GH;r++){ cube_at(cellx(-1), celly(r), 0, FIXF(0.45f), RGB(40,40,60)); cube_at(cellx(GW), celly(r), 0, FIXF(0.45f), RGB(40,40,60)); }
+    n64_number(8,6,(unsigned)score,RGB(255,255,255));
+}
+
+int main(void)
+{
+    n64_init();
+    n64_srand(0xD0D0);
+    state=TITLE; prev_pad=0;
+    for(;;){
+        unsigned int pad = n64_pad();
+        if(state==TITLE){
+            static fix t; t+=FIX(3);
+            n64_clear(RGB(20,12,30));
+            n64_camera(0,0,FIX(-6),0,0);
+            n64_model(0,0,0,t); cube_at(0,0,0,FIX(1),RGB(80,150,255));
+            if((pad&PAD_START)&&!(prev_pad&PAD_START)){ reset_game(); state=PLAY; }
+            prev_pad=pad;
+        } else if(state==PLAY){ update(); render(); }
+        else {
+            n64_clear(RGB(30,8,8));
+            n64_number(110,100,(unsigned)score,RGB(255,120,120));
+            n64_number(120,130,(unsigned)hi,RGB(255,255,120));
+            if((pad&PAD_START)&&!(prev_pad&PAD_START)){ reset_game(); state=PLAY; }
+            prev_pad=pad;
+        }
+        n64_flip();
+    }
+    return 0;
+}