romdevtools 0.86.0 → 0.87.1

package/AGENTS.md

@@ -4,7 +4,7 @@ This is romdev's GENERIC orientation — read it once. The platform-specific det
 
 ## What this server does
 
-Drives the full homebrew ROM dev loop for 18 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2, plus the open-hardware GameTank — and the 3D consoles Nintendo 64, Sony PlayStation, and Sega Dreamcast). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace where an on-screen graphic comes from (`watch({on:'copy'})` on the 15 classic platforms — writer PC per VRAM write; `watch({on:'dma'})` for Genesis DMA sources), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
+Drives the full homebrew ROM dev loop for 18 retro game platforms (NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Sega Master System, Game Gear, Atari 2600/7800, Atari Lynx, Commodore 64, PC Engine / TurboGrafx-16, and MSX / MSX2, plus the open-hardware GameTank — and the 3D consoles Nintendo 64, Sony PlayStation, and Sega Dreamcast) — plus the **PICO-8** fantasy console (via FAKE-08: a Lua VM, so its own tier — `build` PACKAGES a `.p8` from Lua, `disasm({target:'source'})` reads the cart's Lua instead of machine code, `memory({region:'system_ram'})` reads its 64 KB; cpuState/decompile/tile-inspectors are N/A). Build → run → screenshot → inspect → patch → iterate. Also a strong reverse-engineering kit: disassemble existing ROMs into byte-exact rebuildable projects (`disasm({target:'project'})`/`disasm({target:'references'})` — the workhorse for any structural hack), find a value's address with the Cheat-Engine search loop (`memory({op:'search'})`/`memory({op:'searchNext'})`), find the EXACT instruction that wrote a RAM byte (`breakpoint({on:'write'})`, a core-level write watchpoint), confirm a patch is live in the running image (`memory({op:'readCart'})`), tell whether a "found table" is really ASCII (`memory({op:'classify'})`), trace where an on-screen graphic comes from (`watch({on:'copy'})` on the 15 classic platforms — writer PC per VRAM write; `watch({on:'dma'})` for Genesis DMA sources), drive menus by screen-change (`navigate`), and look up cheats (`cheats({op:'lookup'})`/`cheats({op:'search'})`: a free, crowd-sourced labeled RAM/code map for known ROMs), apply + create cheats, convert assets, study patterns from real games. **Doing a romhack? Start with `platform({op:'doc', platform:'romhacking', name:'playbook'})`** — the decision tree that wires all of the above together. Bundled WASM toolchains and emulator cores — no system dependencies, no installs.
 
 You drive the work. The human is a director — they may want a game, a ROM disassembly, a tool-assisted reverse-engineering session, or anything else this server can do.
 

package/README.md

@@ -1,6 +1,6 @@
 # romdev
 
-The entry point for **romdev** — vibe-code real retro games. Build, run, inspect, and reverse-engineer actual homebrew ROMs (NES, SNES, Game Boy, Genesis, Atari, C64, GBA, PC Engine, MSX, GameTank — and the 3D consoles N64, PlayStation, and Dreamcast) with one command — drive it yourself or let a coding assistant do it.
+The entry point for **romdev** — vibe-code real retro games. Build, run, inspect, and reverse-engineer actual homebrew ROMs (NES, SNES, Game Boy, Genesis, Atari, C64, GBA, PC Engine, MSX, GameTank — and the 3D consoles N64, PlayStation, and Dreamcast), plus the **PICO-8** fantasy console (via FAKE-08), with one command — drive it yourself or let a coding assistant do it.
 
 ```bash
 npx romdevtools
@@ -13,6 +13,8 @@ npx romdevtools
 - **Inspect + romhack** — read CPU/video/save RAM, watch memory, write-breakpoints, the Cheat-Engine value-search loop, a bundled cheat database, mapper-aware disassembly, and a byte-exact rebuildable-project disassembler.
 - **Reverse-engineering analysis engine (all 18 platforms — incl. the 3D consoles' MIPS R3000/R4300 + SH-4)** — control-flow graphs, deep cross-references, auto-detected functions (ranked real-code-first), a one-shot structural map, and a Ghidra **decompiler** (C-like pseudocode, with hardware registers named and 6502 SLEIGH clutter folded to readable C): `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`. And the piece no static tool has: **live computed-jumptable recovery** — `breakpoint({on:'jumptable'})` runs the emulator to resolve the `JMP (table,X)` / RTS-trick dispatchers (state machines, script/battle VMs) that static analysis collapses to "could not recover." Understand *how* a routine works before you touch it — no $3,000 IDA license, no install.
 - **Convert assets** — PNG → platform tiles/tilemaps, quantize-to-palette, audio importers (BRR for SNES, XGM2 PCM for Genesis).
+- **Native game runtimes (beyond emulation)** — the same run/see/drive loop also hosts two *native* game formats: **wasmcart** (`.wasc` — WASM games from any language; 2026) and **jsgame** (`.jsgame` — JavaScript canvas/WebGL games; 2024). `loadMedia({platform:'wasmcart'|'jsgame'})` → `frame({op:'step'|'screenshot'})` → `input`, over the same tools — plus V8/WASM introspection (the cart's live WASM heap + exports; the JS game's globals) an emulator can't offer, and `pack({target:'wasc'|'jsgame'})` to zip a source dir into the distributable archive (the "build" step; romdev doesn't compile the WASM — bring your own). A capability descriptor marks the emulator-only tools (memory regions / cpuState / disasm) *not-applicable* for these kinds. Depends on the [`wasmcart`](https://www.npmjs.com/package/wasmcart) + [`rungame`](https://www.npmjs.com/package/rungame) packages (jsgame runs in a `vm` realm — the server self-re-execs with `--experimental-vm-modules`).
+- **PICO-8 (fantasy console)** — the [FAKE-08](https://github.com/jtothebell/fake-08) player (MIT, no BIOS) runs PICO-8 `.p8` (Lua source) and `.p8.png` (cart-in-a-label-PNG) carts at 128×128 with sound. `loadMedia({platform:'pico8'})` → `frame`/`input` work like any core; `build({platform:'pico8', source: lua})` PACKAGES a runnable `.p8` from Lua (+ optional gfx/sfx/map sections) — it's a cart assembler, not a CPU compiler (the Lua IS the code). PICO-8 is a Lua VM, so instead of machine-code disasm/decompile you read the cart's Lua directly with `disasm({target:'source'})`; `memory({region:'system_ram'})` exposes the full 64KB PICO-8 address space (sprite sheet, map, sfx, general RAM, screen buffer). Its capability descriptor is a `fantasy` tier — cpuState/decompile/tile-inspectors report *not-applicable* (there's no CPU or tile hardware to inspect). Ships the [`romdev-core-fake08`](https://www.npmjs.com/package/romdev-core-fake08) core package.
 
 Point any coding agent at it three ways:
 
@@ -36,13 +38,14 @@ This package contains all the JavaScript — the tool surface, the WASM emulator
 
 `romdevtools` depends on the binary/data packages it needs (exact-pinned), so a single install gets a matched, tested set:
 
-- 2D cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem,geargrafx,bluemsx,gametank}`
+- 2D cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem,geargrafx,bluemsx,gametank,fake08}`
 - 3D / GPU cores (rendered through `native-gles`): `romdev-core-{parallel-n64,beetle-psx-hw,flycast}`
 - Platforms (core + dedicated toolchain bundled): `romdev-platform-{snes,gba,atari2600}`
 - Toolchains: `romdev-toolchain-{cc65,sdcc,m68k-gcc,vasm,rgbds,mips-gcc,sh-gcc}` (mips-gcc = N64/PS1 C; sh-gcc = Dreamcast C)
 - GPU deps (OPTIONAL — only the 3D cores need them; the 2D cores never touch GL): `native-gles` + `webgl-node`. A headless user without a GPU stack can still run all the 2D platforms.
 - Analysis: `romdev-analysis` (Rizin → WASM: control-flow graphs, cross-references, function detection) and `romdev-analysis-decompiler` (Ghidra's C++ decompiler → WASM + SLEIGH processor specs for all 18 CPUs, incl. MIPS R3000/R4300 + SH-4). Power `disasm({target:'cfg'|'xrefs'|'functions'|'decompile'})` and `symbols({op:'analyze'})`. Lazy-loaded on first use.
 - Data: `romdev_game_codes` — the bundled game-code / cheat database (a free labeled RAM/code map for thousands of known ROMs), split out so it can grow independently. Lazy-loaded one platform at a time.
+- Native runtimes: [`wasmcart`](https://www.npmjs.com/package/wasmcart) (runs `.wasc` WASM game carts) and [`rungame`](https://www.npmjs.com/package/rungame) (runs `.jsgame` JavaScript games headlessly). Also `romdev-audio-resampler` (WASM+SIMD S16-stereo resampler, used by the live-window audio sink).
 
 `@kmamal/sdl` is used only by `playtest()` / `romdevtools-cli play` (the live window). It ships its native binary via its own install script, which npm skips when romdev is a transitive dep (e.g. under `npx`) — so romdev's `postinstall` fetches it, and `playtest()` also self-heals at runtime if the binary is still missing (downloading the prebuilt before the first window open). Either way, if the binary can't be fetched (offline/locked-down network), the headless server is unaffected — only the live window degrades, and the error tells you the one command to fix it.
 

package/examples/README.md

@@ -27,6 +27,7 @@ Each example fits the convention:
 | pce          | `pce/<template>/main.c` | cc65 (HuC6280) | HuCard homebrew, no BIOS. Ships a direct-register VDC/PSG helper lib (`pce.h` + `pce.lib`) — cc65 has no PCE sprite/sound library. Examples: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre games (shmup/platformer/puzzle/sports/racing). **`#include <stdint.h>`** for int8/16/32_t — `pce.h` only typedefs u8/u16. The genre games fill the BAT (32×32 virtual screen); the platformer smooth-scrolls via the VDC BXR register. |
 | msx          | `msx/<template>/main.c` | sdcc (z80) | Boots cartridge homebrew on the open C-BIOS (no proprietary ROM). Ships an AY-3-8910 + TMS9918/V9938 VDP helper lib (`msx_hw.h` + `msx_vdp.c`). Examples: `sprite_move`, `catch_game`, `music_sfx`, plus the 5 genre games. The bundled `msx_crt0.s` (applied by the dir-build recipe automatically) emits the `"AB"` cartridge header at $4000 + INIT pointer — **C-BIOS shows its logo for ~2-3 s, then CALLs INIT**, so run ≥240 frames before screenshotting. The platformer column-streams the SCREEN 2 name table for a tile-by-tile scroll. |
 | gametank     | `gametank/templates/*.c` | cc65 (W65C02S) | Build with `linkerConfig:"sdk"` + the bundled SDK runtime (`src/platforms/gametank/lib/gt/*`). FIVE complete genre games, fully reworked and play-tested on real hardware (RetroDeck): `shmup`, `platformer`, `puzzle` (CHROMA WELL — a Columns-style 3-jewel matcher), `sports` (2-player paddle), `racing`. The GameTank is a **framebuffer + blitter** machine — NO tilemap/nametable: every frame is redrawn from scratch via the SDK **draw QUEUE** (`gt_draw.h`), the only correct way to drive the blitter (synchronous blits corrupt the FB + tank the framerate). Shared helper headers the games fork: `gt_draw.h` (queue wrappers + `rnd8`), `gt_palette.h` (VERIFIED color indices), `gt_sprites.h` (GRAM sprite load/blit), `gt_hud.h` (box-font digits + 3×5 A–Z text), `gt_sound.h` (one-shot ACP SFX). **HARD-WON GOTCHAS (all documented in `gt_draw.h`): (1) a box of width OR height 128 is silently DROPPED — clamp to 127; (2) box top-edge scanlines flicker between the double-buffer pages — finish a frame that draws near the top with `queue_clear_border(topColor)`; (3) use `rnd8()`, NOT the SDK `rnd()`, which corrupts state on this single-bank build.** Per-frame GRAM **sprite** blits are the expensive part — too many overrun vblank and the queue drops draws (flicker), so keep sprites few (e.g. the platformer blits only the hero; coins are rects). |
+| pico8        | `pico8/templates/*.p8` | Lua (FAKE-08) | FIVE complete genre games, each a full `.p8` cart (no compiler/crt0 — the Lua IS the code): `shmup` (STAR SWEEPER), `platformer` (HOP QUEST), `puzzle` (COLOR DROP), `sports` (RALLY VOLLEY, 1P-vs-CPU or 2P), `racing` (LANE RUNNER). Each carries hand-authored `__gfx__` pixel-art sprites (drawn with `spr()`), looping `__music__` + `__sfx__` banks, title/play/game-over states, and the genre's core mechanics. **`build({platform:'pico8', source: <the .p8 text>})` just PACKAGES the cart** (a `.p8` = header + `__lua__` + optional `__gfx__`/`__gff__`/`__map__`/`__sfx__`/`__music__` sections). PICO-8 is a Lua VM (128×128, 16-color, 6 buttons) — read/edit the Lua directly, no disassembly needed. |
 
 ## Guides
 

package/examples/pico8/templates/platformer.p8

@@ -0,0 +1,168 @@
+pico-8 cartridge // http://www.pico-8.com
+version 18
+__lua__
+-- hop quest — a platformer scaffold
+-- genre example for romdev/pico8. real hero sprite w/ walk + jump frames
+-- (see __gfx__), looping music, sfx, gravity + solid-box collision,
+-- animated spinning coins, a goal flag, parallax hills. fork it.
+
+-- sprites: 1 idle,2 walk,3 jump · 5..8 coin spin frames · 10 flag
+
+function _init()
+ best=99
+ state="title"
+ boot=0
+ build_level()
+ reset_player()
+ music(0)
+end
+
+function build_level()
+ solids={
+  {0,120,128,8},{24,100,24,6},{60,84,30,6},
+  {98,64,24,6},{6,58,18,6},{40,42,28,6},
+ }
+ coins={}
+ for c in all({{34,90},{72,74},{108,54},{14,48},{50,32}}) do
+  add(coins,{x=c[1],y=c[2],f=rnd(4)})
+ end
+ goal={x=52,y=24}
+end
+
+function reset_player()
+ p={x=6,y=104,dx=0,dy=0,grounded=false,face=1,anim=0}
+ collected=0 total=#coins t=0
+end
+
+function solid_at(x,y)
+ for s in all(solids) do
+  if x>=s[1] and x<s[1]+s[3] and y>=s[2] and y<s[2]+s[4] then return true end
+ end
+ return false
+end
+
+-- the top Y of a platform the feet CROSS this step: feet were at/above the top (oldy)
+-- and reach at/below it (newy). returns the highest such top, or nil. this catch-the-
+-- crossing test is what stops fast falls from tunneling straight through a platform.
+function ground_top(x,oldy,newy)
+ local best=nil
+ for s in all(solids) do
+  local top=s[2]
+  if x>=s[1] and x<s[1]+s[3] and oldy<=top+1 and newy>=top then
+   if best==nil or top<best then best=top end
+  end
+ end
+ return best
+end
+
+function _update()
+ t+=1
+ for c in all(coins) do c.f+=.2 end
+ if state=="title" then
+  boot+=1
+  if boot>10 and (btnp(4) or btnp(5)) then state="play" build_level() reset_player() music(-1) end
+  return
+ end
+ if state=="win" then
+  if btnp(4) or btnp(5) then state="title" end
+  return
+ end
+
+ local ax=0
+ if btn(0) then ax=-1 p.face=-1 end
+ if btn(1) then ax=1 p.face=1 end
+ p.dx=ax*1.6
+ if ax~=0 then p.anim+=.25 else p.anim=0 end
+
+ if (btn(4) or btn(2)) and p.grounded then p.dy=-4.2 p.grounded=false sfx(0) end
+ p.dy=min(p.dy+.3,4)
+
+ -- horizontal move (block at body height)
+ local nx=p.x+p.dx
+ if not solid_at(nx+(p.dx>0 and 3 or -3),p.y-3) then p.x=nx end
+
+ -- vertical move. p.y = the FEET. land exactly on a platform's top edge.
+ local ny=p.y+p.dy
+ if p.dy>=0 then
+  -- falling: if the feet CROSS a platform top this step, snap onto it (no tunneling).
+  local gt=ground_top(p.x,p.y,ny)
+  if gt~=nil then
+   p.y=gt p.dy=0 p.grounded=true
+  else
+   p.y=ny p.grounded=false
+  end
+ else
+  -- rising: bonk head on a ceiling
+  if solid_at(p.x,ny-7) then p.dy=0 else p.y=ny end
+  p.grounded=false
+ end
+ p.x=mid(4,p.x,124)
+ if p.y>140 then reset_player() sfx(3) end
+
+ for c in all(coins) do
+  if abs(c.x-p.x)<6 and abs(c.y-p.y)<7 then del(coins,c) collected+=1 sfx(1) end
+ end
+ if abs(goal.x-p.x)<7 and abs(goal.y-p.y)<9 then
+  best=min(best,t\30) state="win" sfx(2) music(-1)
+ end
+end
+
+function _draw()
+ cls(12)
+ -- parallax hills
+ for i=0,4 do circfill(i*34-8,126,22,3) end
+ for i=0,3 do circfill(i*44+20,128,26,11) end
+
+ if state=="title" then
+  print("hop quest",44,44,7)
+  spr(1,60,60)
+  print("z/up  jump",40,80,6)
+  print("z/x  start",40,92,7)
+  return
+ end
+
+ for s in all(solids) do
+  rectfill(s[1],s[2],s[1]+s[3]-1,s[2]+s[4]-1,4)
+  rectfill(s[1],s[2],s[1]+s[3]-1,s[2],9)  -- grass top
+ end
+ for c in all(coins) do spr(5+flr(c.f)%4,c.x-4,c.y-4) end
+ -- flag
+ rectfill(goal.x,goal.y,goal.x,goal.y+12,6)
+ spr(10,goal.x,goal.y-1)
+ -- hero
+ local s=p.grounded and (p.dx~=0 and (5+flr(p.anim)%2==5 and 2 or (flr(p.anim)%2==0 and 1 or 2)) or 1) or 3
+ spr(p.dx~=0 and (flr(p.anim)%2==0 and 1 or 2) or (p.grounded and 1 or 3),p.x-4,p.y-7,1,1,p.face<0)
+
+ rectfill(0,0,127,7,0)
+ print("coins "..collected.."/"..total,2,1,10)
+ if best<99 then print("best "..best.."s",84,1,6) end
+ if state=="win" then
+  rectfill(28,50,100,80,0) rect(28,50,100,80,11)
+  print("you win!",44,55,11)
+  print("time "..(t\30).."s",44,64,7)
+  print("z/x  title",40,72,6)
+ end
+end
+
+__gfx__
+0000000000fff00000fff00080fff0080000000000aaaa00000aa0000000a000000aa00000066000066000000000000000000000000000000000000000000000
+0000000000fff00000fff00008fff880000000000a9779a000a99a00000a9a0000a99a0000066660066600000000000000000000000000000000000000000000
+0000000000f4f00000f4f00000f4f00000000000a977779a0a9779a0000a9a000a9779a000060000066660000000000000000000000000000000000000000000
+0000000008888000088880000088880000000000a977779a0a9779a0000a9a000a9779a000060000066600000000000000000000000000000000000000000000
+0000000008888000088880000088880000000000a999999a0a9999a0000a9a000a9999a000600000066000000000000000000000000000000000000000000000
+0000000008880000088800000008800000000000a999999a0a9999a0000a9a000a9999a000060000060000000000000000000000000000000000000000000000
+00000000008008000088000000800800000000000a9999a000a99a00000a9a0000a99a0000060000060000000000000000000000000000000000000000000000
+0000000000b00b00000bb00000b00b000000000000aaaa00000aa0000000a000000aa00000060000060000000000000000000000000000000000000000000000
+__sfx__
+000300001f04025040290400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000200002465527655296550000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+011000002465521655216551d6551a655000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010600000865505655036550000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+001400001c4501c4501d4501f4501f4501d4501c4501a45018450184501a4501c4501c4501a4501a4501a4501c4501c4501d4501f4501f4501d4501c4501a45018450184501a4501c4501a450184501845018450
+001400000c2300c2300c2301323013230132300c230132300c2300c230132300c2300c2301323013230132300c2300c2300c2301323013230132300c230132300c2300c230132300c230132300c2300c2300c230
+__music__
+03 08094040

package/examples/pico8/templates/puzzle.p8

@@ -0,0 +1,240 @@
+pico-8 cartridge // http://www.pico-8.com
+version 18
+__lua__
+-- color drop — a falling-column match puzzle (Columns-style) scaffold
+-- genre example for romdev/pico8. THE GAME: a vertical column of 3 jewels
+-- falls into an 8-wide well. move left/right, soft-drop (down), hard-drop
+-- (x), and CYCLE the 3 colors (o). match 3+ of one color horizontally,
+-- vertically, or DIAGONALLY to clear; gravity pulls survivors down, which
+-- can CASCADE into more clears. fork it and reshape one thing at a time.
+
+cols=8 rows=13 cell=9 ox=26 oy=3
+ncol=5  -- jewel colors 1..5
+-- well fits the 128px screen: oy + rows*cell = 3 + 117 = 120 (bottom row fully visible).
+
+function _init()
+ hi=0
+ state="title"
+ boot=0
+ reset_game()
+
+ music(0)
+end
+
+function reset_game()
+ grid={}
+ for y=1,rows do grid[y]={} for x=1,cols do grid[y][x]=0 end end
+ score=0 chain=0 level=1 cleared=0
+ fall=0 t=0
+ flashing=nil  -- {cells=..,ttl=..} during a clear
+ nextp=randcol3()
+ spawn_piece()
+end
+
+function randcol3()
+ return {flr(rnd(ncol))+1,flr(rnd(ncol))+1,flr(rnd(ncol))+1}
+end
+
+-- the falling column: 3 colors top->bottom at (px, py=top cell)
+function spawn_piece()
+ pcol=nextp
+ nextp=randcol3()
+ px=flr(cols/2) py=1
+ -- game over if the top cells are blocked
+ if grid[1][px]~=0 or grid[2][px]~=0 or grid[3][px]~=0 then
+  hi=max(hi,score) state="over"
+ end
+end
+
+function can_be(x,y)
+ -- can the 3-tall column sit with its TOP cell at (x,y)?
+ for i=0,2 do
+  local cy=y+i
+  if cy>rows then return false end
+  if cy>=1 and grid[cy][x]~=0 then return false end
+ end
+ return true
+end
+
+function _update()
+ t+=1
+
+ -- resolve an in-progress clear (flash then remove + cascade)
+ if flashing then
+  flashing.ttl-=1
+  if flashing.ttl<=0 then
+   for c in all(flashing.cells) do grid[c.y][c.x]=0 end
+   collapse()
+   local m=find_matches()
+   if #m>0 then chain+=1 start_clear(m)
+   else chain=0 flashing=nil spawn_piece() end
+  end
+  return
+ end
+
+ if state=="title" then
+  boot+=1
+  if boot>10 and (btnp(4) or btnp(5)) then state="play" reset_game() music(-1) end
+  return
+ end
+ if state=="over" then
+  if btnp(4) or btnp(5) then state="title" end
+  return
+ end
+
+ -- move — snappy custom repeat (move on press, then again every 4 frames while held)
+ -- so a hold slides smoothly instead of pico-8's slow 15-frame btnp repeat.
+ hold_l = btn(0) and (hold_l or 0)+1 or 0
+ hold_r = btn(1) and (hold_r or 0)+1 or 0
+ if (hold_l==1 or (hold_l>4 and hold_l%3==0)) and px>1 and can_be(px-1,py) then px-=1 sfx(2) end
+ if (hold_r==1 or (hold_r>4 and hold_r%3==0)) and px<cols and can_be(px+1,py) then px+=1 sfx(2) end
+ -- cycle colors (o = btn4): rotate the 3-jewel column
+ if btnp(4) then
+  pcol={pcol[3],pcol[1],pcol[2]} sfx(3)
+ end
+ -- hard drop (x = btn5)
+ if btnp(5) then
+  while can_be(px,py+1) do py+=1 end
+  lock_piece() return
+ end
+
+ -- gravity (soft-drop on down)
+ local speed=btn(3) and 2 or max(6,26-level*2)
+ fall+=1
+ if fall>=speed then
+  fall=0
+  if can_be(px,py+1) then py+=1
+  else lock_piece() end
+ end
+end
+
+function lock_piece()
+ for i=0,2 do
+  local cy=py+i
+  if cy>=1 and cy<=rows then grid[cy][px]=pcol[i+1] end
+ end
+ sfx(0)
+ local m=find_matches()
+ if #m>0 then chain=1 start_clear(m)
+ else spawn_piece() end
+end
+
+function start_clear(cells)
+ flashing={cells=cells,ttl=12}
+ score+=#cells*10*chain
+ cleared+=#cells
+ level=1+flr(cleared/20)
+ sfx(1)
+end
+
+-- scan H, V, and both diagonals for runs of 3+ same color.
+-- returns a list of {x,y} cells to clear (deduped).
+local dirs={{1,0},{0,1},{1,1},{1,-1}}
+function find_matches()
+ local hit={}  -- key "x,y" -> {x,y}
+ for y=1,rows do for x=1,cols do
+  local c=grid[y][x]
+  if c~=0 then
+   for d in all(dirs) do
+    -- only start a run at its beginning (no same-color cell behind us)
+    local bx,by=x-d[1],y-d[2]
+    local prev = (bx>=1 and bx<=cols and by>=1 and by<=rows) and grid[by][bx] or -1
+    if prev~=c then
+     local run={}
+     local cx,cy=x,y
+     while cx>=1 and cx<=cols and cy>=1 and cy<=rows and grid[cy][cx]==c do
+      add(run,{x=cx,y=cy}) cx+=d[1] cy+=d[2]
+     end
+     if #run>=3 then for r in all(run) do hit[r.x..","..r.y]={x=r.x,y=r.y} end end
+    end
+   end
+  end
+ end end
+ local out={} for _,v in pairs(hit) do add(out,v) end
+ return out
+end
+
+-- gravity: drop every column's survivors to the bottom
+function collapse()
+ for x=1,cols do
+  local w=rows
+  for y=rows,1,-1 do
+   if grid[y][x]~=0 then
+    grid[w][x]=grid[y][x] if w~=y then grid[y][x]=0 end w-=1
+   end
+  end
+ end
+end
+
+-- ── draw ──
+gemcol={8,9,10,11,12}
+function drawgem(gx,gy,c)
+ local base=gemcol[c] or 8
+ rectfill(gx+1,gy,gx+6,gy+7,base)
+ rectfill(gx,gy+1,gx+7,gy+6,base)
+ rectfill(gx+2,gy+1,gx+3,gy+2,7)   -- sparkle
+ line(gx+1,gy+6,gx+6,gy+6,1)       -- shadow
+end
+
+function _draw()
+ cls(0)
+ rectfill(0,0,ox-2,127,1)
+ rectfill(ox+cols*cell+1,0,127,127,1)
+
+ if state=="title" then
+  print("color drop",42,40,12)
+  -- show a sample 3-jewel column
+  for i=1,3 do drawgem(60,50+i*9,i) end
+  print("arrows move",34,86,7)
+  print("o cycle  x drop",26,96,6)
+  print("z/x  start",40,108,7)
+  return
+ end
+
+ rect(ox-1,oy-1,ox+cols*cell,oy+rows*cell,5)
+ -- placed gems
+ for y=1,rows do for x=1,cols do
+  if grid[y][x]~=0 then drawgem(ox+(x-1)*cell,oy+(y-1)*cell,grid[y][x]) end
+ end end
+ -- flashing clears
+ if flashing then
+  for c in all(flashing.cells) do
+   if t%4<2 then rectfill(ox+(c.x-1)*cell,oy+(c.y-1)*cell,ox+(c.x-1)*cell+8,oy+(c.y-1)*cell+8,7) end
+  end
+ elseif state=="play" then
+  -- the falling 3-jewel column
+  for i=0,2 do
+   local cy=py+i
+   if cy>=1 then drawgem(ox+(px-1)*cell,oy+(cy-1)*cell,pcol[i+1]) end
+  end
+ end
+
+ -- panel
+ print("score",102,8,7) print(score,102,16,10)
+ print("next",102,36,7)
+ for i=1,3 do drawgem(106,44+i*9,nextp[i]) end
+ print("lv "..level,102,76,7)
+ if chain>1 then print("x"..chain,102,88,8) end
+
+ if state=="over" then
+  rectfill(18,52,110,76,0) rect(18,52,110,76,8)
+  print("game over",44,56,8)
+  print("hi "..hi,52,66,10)
+ end
+end
+
+__gfx__
+00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+__sfx__
+010800001c0551c055000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+011000002465527655296552d65500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010400001865518655000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010c00002465521655000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0014000028450274502845027450284502345026450244502145000000184501c4502145023450000001c450204502345024450000001c4502845027450284502745028450234502645024450214500000000000
+001400001523000000000000000015230000000000000000102300000000000000000c23000000000000000015230000000000000000152300000000000000001023000000000000000015230000000000000000
+__music__
+03 08094040

package/examples/pico8/templates/racing.p8

@@ -0,0 +1,122 @@
+pico-8 cartridge // http://www.pico-8.com
+version 18
+__lua__
+-- lane runner — a top-down endless racing scaffold
+-- genre example for romdev/pico8. car sprites (see __gfx__), looping
+-- music, engine/crash sfx, 3-lane dodging, scrolling road + dashes,
+-- speed ramp, distance score + best. fork it.
+
+function _init()
+ best=0
+ state="title"
+ boot=0
+ reset_run()
+ music(0)
+
+end
+
+function reset_run()
+ car={x=64,lane=1}
+ lanes={40,64,88}
+ rivals={}
+ dist=0 speed=2 spawn=0 road=0 t=0 shake=0
+end
+
+function _update()
+ t+=1
+ road=(road+speed)%16
+ if shake>0 then shake-=1 end
+ if state=="title" then
+  boot+=1
+  if boot>10 and (btnp(4) or btnp(5)) then state="play" reset_run() music(-1) end
+  return
+ end
+ if state=="over" then
+  if btnp(4) or btnp(5) then state="title" end
+  return
+ end
+
+ if btnp(0) and car.lane>0 then car.lane-=1 sfx(0) end
+ if btnp(1) and car.lane<2 then car.lane+=1 sfx(0) end
+ car.x=car.x+(lanes[car.lane+1]-car.x)*.4
+
+ speed=min(2+dist/700,5.5)
+ dist+=speed
+
+ spawn-=1
+ if spawn<=0 then
+  add(rivals,{lane=flr(rnd(3)),y=-14,c=flr(rnd(3))})
+  spawn=max(16,44-flr(dist/110))
+ end
+ for r in all(rivals) do
+  r.y+=speed
+  if r.y>140 then del(rivals,r) end
+  if r.lane==car.lane and abs(r.y-104)<13 then
+   sfx(2) shake=12 best=max(best,flr(dist/10)) state="over"
+  end
+ end
+end
+
+function _draw()
+ local sx=shake>0 and (rnd(4)-2) or 0
+ cls(3)
+ camera(sx,0)
+ -- grass texture
+ for i=0,8 do for j=0,8 do if (i+j)%2==0 then pset(i*16+2,j*16+8,11) end end end
+ -- road
+ rectfill(28,0,100,128,5)
+ rectfill(28,0,31,128,10) rectfill(97,0,100,128,10)
+ for y=-16,128,16 do
+  rectfill(52,y+road,54,y+road+9,7)
+  rectfill(74,y+road,76,y+road+9,7)
+ end
+
+ if state=="title" then
+  camera()
+  rectfill(12,42,116,94,0)
+  print("lane runner",40,48,10)
+  spr(1,60,64)
+  print("left/right  swerve",22,80,6)
+  print("z/x  start",40,88,7)
+  if best>0 then print("best "..best,50,100,7) end
+  return
+ end
+
+ for r in all(rivals) do spr(2+r.c,lanes[r.lane+1]-4,r.y-6) end
+ spr(1,car.x-4,104-6)
+
+ camera()
+ rectfill(0,0,127,8,0)
+ print("dist "..flr(dist/10),2,1,7)
+ print("spd "..flr(speed*10),88,1,10)
+
+ if state=="over" then
+  rectfill(22,52,106,80,0) rect(22,52,106,80,8)
+  print("crashed!",46,56,8)
+  print("dist "..flr(dist/10),44,66,7)
+  print("z/x  title",40,74,6)
+ end
+end
+
+__gfx__
+000000000008800000099000000aa000000ee0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000000888800009999000aaaaa000eeeee000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000008777780097777900a7777a00e7777e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000008888880099999900aaaaaa00eeeeee00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000008888880099999900aaaaaa00eeeeee00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000008777780097777900a7777a00e7777e00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000088880000999900000aa000000ee0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000080080000900900000aa000000ee0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+__sfx__
+010800001505013050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010400001f05522055000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010600000c05008050050550000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0012000017350183501a3501c3501a35018350173501a350133501f3501c350133501f3501c350133501f35017350183501a3501c3501a35018350173501a3501c3501d3501f3501d3501c3501a3501835017350
+001200000b230000000b230000000b230000000b230000000c230000000c230000000c230000000c230000000b230000000b230000000b230000000b230000001023000000102300000010230000000b23000000
+__music__
+03 08094040

package/examples/pico8/templates/shmup.p8

@@ -0,0 +1,165 @@
+pico-8 cartridge // http://www.pico-8.com
+version 18
+__lua__
+-- star sweeper — a shmup scaffold
+-- genre example for romdev/pico8. real sprites (see __gfx__), looping
+-- music (__music__), sfx, title/play/gameover states, projectile pool,
+-- wave spawner, aabb collision, score + hi-score, thruster animation.
+-- fork it and reshape one thing at a time.
+
+-- sprite ids in __gfx__:
+--  1 ship, 2 ship-thrust, 3 shot, 4 foe-a, 5 foe-b, 6 explosion
+
+function _init()
+ hi=0
+ make_stars()
+ state="title"
+ boot=0
+ reset_game()
+
+ music(0)
+end
+
+function make_stars()
+ stars={}
+ for i=1,40 do add(stars,{x=rnd(128),y=rnd(128),s=rnd(2)+.4}) end
+end
+
+function reset_game()
+ player={x=60,y=100,cool=0,inv=0}
+ shots={}
+ foes={}
+ boom={}
+ score=0
+ lives=3
+ spawn=0
+ t=0
+end
+
+function _update()
+ t+=1
+ for s in all(stars) do s.y+=s.s if s.y>128 then s.y=0 s.x=rnd(128) end end
+
+ if state=="title" then
+  boot+=1
+  if boot>10 and (btnp(4) or btnp(5)) then state="play" reset_game() music(-1) end
+  return
+ end
+ if state=="over" then
+  if btnp(4) or btnp(5) then state="title" end
+  return
+ end
+
+ -- move
+ local mv=false
+ if btn(0) then player.x-=2 mv=true end
+ if btn(1) then player.x+=2 mv=true end
+ if btn(2) then player.y-=2 end
+ if btn(3) then player.y+=2 end
+ player.x=mid(4,player.x,116)
+ player.y=mid(4,player.y,120)
+ player.inv=max(0,player.inv-1)
+
+ -- fire
+ player.cool=max(0,player.cool-1)
+ if (btn(4) or btn(5)) and player.cool==0 then
+  add(shots,{x=player.x+3,y=player.y-2})
+  player.cool=7 sfx(3)
+ end
+ for s in all(shots) do s.y-=4 if s.y<-4 then del(shots,s) end end
+
+ -- spawn foes (ramping)
+ spawn-=1
+ if spawn<=0 then
+  add(foes,{x=rnd(104)+12,y=-8,vy=rnd(1)+1,vx=rnd(1)-.5,ty=flr(rnd(2))})
+  spawn=max(10,38-flr(t/90))
+ end
+ for f in all(foes) do
+  f.y+=f.vy f.x+=f.vx
+  if f.x<8 or f.x>116 then f.vx=-f.vx end
+  if f.y>134 then del(foes,f) end
+  if player.inv==0 and abs(f.x-player.x)<6 and abs(f.y-player.y)<6 then
+   del(foes,f) hurt()
+  end
+ end
+
+ -- shot vs foe
+ for s in all(shots) do
+  for f in all(foes) do
+   if abs(f.x-s.x)<5 and abs(f.y-s.y)<5 then
+    del(shots,s) del(foes,f)
+    add(boom,{x=f.x,y=f.y,f=0})
+    score+=10 sfx(4)
+    break
+   end
+  end
+ end
+ for b in all(boom) do b.f+=1 if b.f>8 then del(boom,b) end end
+end
+
+function hurt()
+ lives-=1 sfx(5)
+ add(boom,{x=player.x,y=player.y,f=0})
+ player.inv=60
+ if lives<=0 then
+  hi=max(hi,score) state="over"
+ end
+end
+
+function _draw()
+ cls(0)
+ for s in all(stars) do pset(s.x,s.y,s.s>1.6 and 7 or (s.s>1 and 6 or 5)) end
+
+ if state=="title" then
+  print("star sweeper",34,44,12)
+  print("★",26,44,10) print("★",96,44,10)
+  spr(1,60,62)
+  print("z/x  start",40,84,7)
+  print("hi "..hi,50,98,6)
+  print("arrows move · z/x fire",18,116,5)
+  return
+ end
+
+ for f in all(foes) do spr(f.ty==0 and 4 or 5,f.x-4,f.y-4) end
+ for s in all(shots) do spr(3,s.x-4,s.y-4) end
+ for b in all(boom) do spr(6,b.x-4,b.y-4) end
+ -- ship (blink when invulnerable)
+ if not (player.inv>0 and player.inv%4<2) then
+  spr((t%8<4) and 2 or 1,player.x-4,player.y-4)
+ end
+
+ rectfill(0,0,127,7,1)
+ print("score "..score,2,1,7)
+ print("hi "..hi,54,1,6)
+ for i=1,lives do spr(1,96+i*8,0) end
+
+ if state=="over" then
+  rectfill(28,52,100,80,0) rect(28,52,100,80,8)
+  print("game over",44,56,8)
+  print("score "..score,42,66,7)
+  print("z/x  title",40,74,6)
+ end
+end
+
+__gfx__
+00000000000c000000000c00000aa000000880000088880000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000000ccc00000ccc0000aaaa000008888000899998000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0070070000ccc00000ccc0000a00a000088888000988889000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000770000cccccc00cc7cc00aa00aa008899988089aaaa9800000000000000000000000000000000000000000000000000000000000000000000000000000000
+000770000c7cc7c00c7cc7c0a0a00a0a0899998008aaaa8000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0070070000c00c0000cccc00a000000a088888000899998000000000000000000000000000000000000000000000000000000000000000000000000000000000
+00000000000000000090900000a00a00008888000089980000000000000000000000000000000000000000000000000000000000000000000000000000000000
+00000000000000000090000000000000000880000008800000000000000000000000000000000000000000000000000000000000000000000000000000000000
+__sfx__
+010c00000c6530e6530c6530000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010c00001805518055180551805518055180551305513055130551305511055110550e0550e0550e0550e0550c0550c0550c0550c055000000000000000000000000000000000000000000000000000000000000
+011c00002465524655216551d65500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000200003065528655236551e6551a655166551265510655000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+00030000186550f6550c6550a65508655066550465502655006550065500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010500000c6530a653086530565303653016530000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0012000024250242502b2502b2502d2502d2502b2500000029250292502825028250262502625024250000002b2502b2502925029250282502825026250000002b2502b250292502925028250282502625000000
+00120000182300000018230000001d230000001d230000001a230000001a23000000182300000018230000001d230000001d230000001a230000001a230000001d230000001d2300000018230000001823000000
+__music__
+03 08094040

package/examples/pico8/templates/sports.p8

@@ -0,0 +1,140 @@
+pico-8 cartridge // http://www.pico-8.com
+version 18
+__lua__
+-- rally volley — a 2-player paddle sports scaffold
+-- genre example for romdev/pico8. paddle + ball sprites (see __gfx__),
+-- looping music, bounce sfx, angle-off-paddle physics, speed-up on rally,
+-- 1p-vs-cpu or 2p couch mode, first to 5. fork it.
+
+function _init()
+ state="title"
+ boot=0
+ ai=true
+ reset_match()
+
+ music(0)
+end
+
+function reset_match()
+ lp={y=64,score=0} rp={y=64,score=0}
+ rally=0
+ serve(pick_dir())
+end
+
+function pick_dir() return (rnd(1)<.5) and -1 or 1 end
+
+function serve(dir)
+ ball={x=64,y=64,dx=dir*1.4,dy=(rnd(2)-1)*1.1}
+ wait=36
+end
+
+function _update()
+ if state=="title" then
+  boot+=1
+  if btnp(2) or btnp(3) then ai=not ai sfx(3) end
+  if boot>10 and (btnp(4) or btnp(5)) then state="play" reset_match() music(-1) end
+  return
+ end
+ if state=="over" then
+  if btnp(4) or btnp(5) then state="title" end
+  return
+ end
+
+ if btn(2) then lp.y-=2 end
+ if btn(3) then lp.y+=2 end
+ lp.y=mid(12,lp.y,116)
+
+ if ai then
+  if ball.dx>0 then rp.y+=mid(-2,(ball.y-rp.y)*.11,2) end
+ else
+  if btn(4) then rp.y-=2 end
+  if btn(5) then rp.y+=2 end
+ end
+ rp.y=mid(12,rp.y,116)
+
+ if wait>0 then wait-=1 return end
+
+ ball.x+=ball.dx ball.y+=ball.dy
+ if ball.y<4 or ball.y>123 then ball.dy=-ball.dy sfx(0) end
+
+ if ball.dx<0 and ball.x<9 and abs(ball.y-lp.y)<11 then
+  ball.dx=abs(ball.dx)+.12 ball.dy+=(ball.y-lp.y)*.07 rally+=1 sfx(1)
+ end
+ if ball.dx>0 and ball.x>119 and abs(ball.y-rp.y)<11 then
+  ball.dx=-abs(ball.dx)-.12 ball.dy+=(ball.y-rp.y)*.07 rally+=1 sfx(1)
+ end
+ ball.dy=mid(-3,ball.dy,3)
+
+ if ball.x<0 then rp.score+=1 point() end
+ if ball.x>128 then lp.score+=1 point() end
+end
+
+function point()
+ sfx(2) rally=0
+ if lp.score>=5 or rp.score>=5 then
+  winner=lp.score>rp.score and "left" or "right"
+  state="over"
+ else
+  serve(pick_dir())
+ end
+end
+
+-- a tall paddle bar (10 tall, 3 wide) with a lighter core so it reads clearly
+function paddle(x,y,col)
+ rectfill(x,y-9,x+2,y+9,col)
+ rectfill(x+1,y-8,x+1,y+8,7)  -- white core stripe
+end
+
+function _draw()
+ cls(0)
+ -- dashed center net
+ for y=2,124,8 do rectfill(63,y,64,y+4,5) end
+
+ if state=="title" then
+  print("rally volley",38,36,12)
+  paddle(24,64,12) paddle(102,64,8)
+  rectfill(62,62,65,65,7)  -- ball
+  print("mode: "..(ai and "1p vs cpu" or "2 player"),34,80,7)
+  print("up/down  toggle",30,90,6)
+  print("z/x  start",40,102,7)
+  return
+ end
+
+ paddle(4,lp.y,12)      -- left paddle (blue, player 1)
+ paddle(121,rp.y,8)     -- right paddle (red, cpu/p2)
+ rectfill(ball.x-1,ball.y-1,ball.x+1,ball.y+1,7)  -- ball
+
+ rectfill(0,0,127,8,0)
+ print(lp.score,40,2,12)
+ print(rp.score,84,2,8)
+ if rally>2 then print("rally "..rally,52,2,10) end
+
+ if state=="over" then
+  rectfill(24,52,104,78,0) rect(24,52,104,78,11)
+  print(winner.." wins!",38,58,11)
+  print(lp.score.." - "..rp.score,52,68,7)
+ end
+end
+
+__gfx__
+0000000000cccc000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000cccccc0000cc00000cc0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000c7777c000cccc00cccc0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000c7777c000cccc00cccc0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000c7777c000cccc00cccc0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000cccccc000cccc00cccc0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+0000000000cccc00000cc00000cc0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+__sfx__
+010800001505015050000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010400001f05524055000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+011000000c05508055050550000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+010400001c0551c055000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
+00100000183501c3501d3501f35000000183501c3501d3501f35000000183501c3501d3501f3501c350183501c3501a350000001a3501c3501f3501f3501c3501f3501d3501c3501a35018350000000000000000
+00100000182300000000000000001f230000000000000000182300000000000000001f230000000000000000182300000000000000001d2300000000000000001f23000000000000000018230000000000000000
+__music__
+03 08094040

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.86.0",
+  "version": "0.87.1",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 17 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, PlayStation, N64, Dreamcast, ...) via WASM toolchains + emulator cores. Use over plain HTTP, as an Agent Skill, or as an MCP server.",
   "type": "module",
   "main": "src/mcp/server.js",
@@ -55,6 +55,7 @@
     "romdev-audio-resampler": "0.1.0",
     "romdev-core-beetle-psx-hw": "0.2.0",
     "romdev-core-bluemsx": "0.7.0",
+    "romdev-core-fake08": "0.1.0",
     "romdev-core-fceumm": "0.11.0",
     "romdev-core-flycast": "0.2.0",
     "romdev-core-gambatte": "0.10.0",

package/src/cores/capabilities.js

@@ -198,6 +198,33 @@ export const CAPABILITIES = {
       cart: true, disasm: true, decompile: true,
     },
   },
+  pico8: {
+    // FAKE-08 (MIT) runs PICO-8 carts. PICO-8 is a Lua VM, not a real CPU — so there's
+    // no machine code to disassemble/decompile and no CPU register file (cpuState N/A).
+    // But: build=PACKAGE a .p8 cart (Lua + gfx/sfx/map sections); run/screenshot work;
+    // memory works — the romdev patch exposes the full 64KB PICO-8 address space as
+    // system_ram (sprite sheet, map, flags, music, sfx, general RAM, screen buffer).
+    // disasm here is target:'source' — the cart IS Lua source, so we return the Lua
+    // itself (the honest "understand this cart" path), not a machine-code listing.
+    // It renders to a 128×128 framebuffer (poke to screen memory), so the inspect-*
+    // tile/sprite-table tools are N/A like gametank/the disc platforms.
+    // tier:"fantasy" — a fantasy console (Lua VM), not a CPU emulator. Held to its OWN
+    // conformance, NOT the canonical-14 cross-checks (which assume CPU disasm/decompile/
+    // cpuState/tile inspectors every real console has). Excluded from CONTRACT_PLATFORMS
+    // via NEXTGEN_TIER_PLATFORMS.
+    tier: "fantasy",
+    cpuFamily: "lua", decompileQuality: "n/a",
+    cpus: { main: "", secondary: [] }, // Lua VM — no CPU register file
+    audioChips: [], // audioDebug not wired (PICO-8's synth isn't a fixed-register chip we decode)
+    memoryRegions: [...GENERIC_REGIONS],
+    renderingKind: "framebuffer", introspection: "shallow",
+    ops: {
+      build: true, run: true, screenshot: true,
+      inspectSprites: false, inspectPalette: false, inspectBackground: false,
+      renderingContext: false, cpuState: false, audioDebug: false,
+      cart: false, disasm: true, decompile: false,
+    },
+  },
   pce: {
     cpuFamily: "huc6280", decompileQuality: "medium",
     cpus: { main: "", secondary: [] }, // getCPUState main NOT wired for pce
@@ -316,7 +343,7 @@ export const MIPS_TIER_PLATFORMS = Object.entries(CAPABILITIES)
  *  is held to its OWN conformance, not the "all 14" cross-checks; a new platform
  *  starts here (analysis-first) and graduates as run/build/etc. land. */
 export const NEXTGEN_TIER_PLATFORMS = Object.entries(CAPABILITIES)
-  .filter(([, c]) => c.tier === "mips" || c.tier === "sh")
+  .filter(([, c]) => c.tier === "mips" || c.tier === "sh" || c.tier === "fantasy")
   .map(([p]) => p);
 
 /** Back-compat: the analysis-only set is now empty (PS1/N64 gained run/screenshot

package/src/cores/registry.js

@@ -54,6 +54,11 @@ export const CORES = {
   pce: { platform: "pce", coreName: "geargrafx", pkg: "romdev-core-geargrafx", displayName: "PC Engine / TurboGrafx-16 (Geargrafx)", aka: "turbografx,tg16,pcengine" },
   msx: { platform: "msx", coreName: "bluemsx", pkg: "romdev-core-bluemsx", displayName: "MSX / MSX2 (blueMSX)", aka: "msx2" },
   gametank: { platform: "gametank", coreName: "gametank", pkg: "romdev-core-gametank", displayName: "GameTank (Clyde Shaffer)", aka: "gtr" },
+  // FAKE-08 = open-source (MIT) PICO-8 player, NOT Lexaloffle's PICO-8, no BIOS. Runs
+  // .p8 (Lua source) + .p8.png carts at 128×128. It's a Lua VM, not a real CPU — the
+  // capability descriptor marks cpuState/disasm/memory-region tools not-applicable; the
+  // .p8 Lua source IS the readable "disassembly".
+  pico8: { platform: "pico8", coreName: "fake08", pkg: "romdev-core-fake08", displayName: "PICO-8 (FAKE-08)", aka: "p8,fake08" },
   // 32-bit MIPS tier. These cores HW-render (GL): the host lazy-loads the OPTIONAL
   // webgl-node bridge only when one of these boots (hwRender:true). The other 14 are
   // software-rendered and never touch GL, so a headless user without the GPU module

package/src/host/LibretroHost.js

@@ -212,6 +212,7 @@ export const PLATFORM_VIRTUAL_EXT = {
   atari7800:  ".a78",
   pce:        ".pce",
   msx:        ".rom",
+  pico8:      ".p8",
 };
 import { RETRO_DEVICE_JOYPAD, ROMDEV_PIXEL_FORMAT_RGBA8888 } from "./retroConstants.js";
 import { decodeCode as decodeCheatCode } from "../cheats/gamegenie.js";

package/src/mcp/tools/disasm.js

@@ -1190,6 +1190,59 @@ function renderBuildMd({ platform, romPath, regions, blobs, build, verifiable, n
  * The default endian follows the CPU (Genesis/m68k → BE; everything else → LE),
  * overridable via `endian`.
  */
+/**
+ * target='source' — return a cart's high-level SOURCE instead of a disassembly, for
+ * platforms where the "cart" IS source (not machine code). Today: PICO-8 (.p8 = Lua +
+ * data sections; .p8.png = the same cart embedded in a label PNG). This is the honest
+ * "understand this cart" path for a Lua VM — there's no machine code to disassemble, so
+ * we hand back the actual Lua the game runs, plus a map of the other sections.
+ */
+async function readCartSourceCore(args) {
+  const romPath = requireRomPath(args);
+  const fs = await import("node:fs/promises");
+  const lower = romPath.toLowerCase();
+  const isPng = lower.endsWith(".p8.png");
+  const isP8 = lower.endsWith(".p8");
+  if (!isP8 && !isPng && args.platform !== "pico8") {
+    throw new Error(
+      `disasm({target:'source'}) is for source-form carts (PICO-8 .p8/.p8.png). '${romPath}' isn't one. ` +
+      `For machine-code ROMs use target:'rom'/'project'/'decompile'.`,
+    );
+  }
+  if (isPng) {
+    // A .p8.png embeds the cart in the PNG's low bits — decoding needs the FAKE-08 core.
+    throw new Error(
+      "disasm({target:'source'}): .p8.png carts store the source steganographically in the PNG — " +
+      "load it (loadMedia({platform:'pico8'})) to run it; export the .p8 text form to read the Lua. " +
+      "Pass a plain-text .p8 here to read its source directly.",
+    );
+  }
+  const text = await fs.readFile(romPath, "utf8");
+  // Split on __section__ markers, preserving order.
+  const parts = text.split(/(^__[a-z]+__$)/m);
+  const sections = {};
+  let current = "(header)";
+  let buf = [];
+  const flush = () => { if (buf.length) sections[current] = buf.join("\n").replace(/^\n+|\n+$/g, ""); buf = []; };
+  for (const chunk of parts) {
+    const m = chunk.match(/^__([a-z]+)__$/);
+    if (m) { flush(); current = m[1]; } else { buf.push(chunk); }
+  }
+  flush();
+  return {
+    platform: "pico8",
+    kind: "source",
+    format: ".p8",
+    note: "PICO-8 carts are SOURCE, not machine code — this is the Lua the game runs (+ its data sections). There is no disassembly to do.",
+    lua: sections.lua ?? "",
+    sections: Object.keys(sections),
+    // Include non-lua data sections so callers can see the full cart shape (gfx/map/sfx/music/gff/label).
+    dataSections: Object.fromEntries(
+      Object.entries(sections).filter(([k]) => k !== "lua" && k !== "(header)"),
+    ),
+  };
+}
+
 async function pointerTableCore(args) {
   const { platform, loBase, hiBase, count, convention = "direct", reverseHandler, bank } = args;
   if (loBase == null) throw new Error("disasm({target:'pointerTable'}): loBase (the table / low-byte base) is required.");
@@ -1485,11 +1538,11 @@ export function registerDisasmTools(server, z) {
     "LLM folds it. `address` for all four comes from target:'functions' (a CPU/virtual address; the file-offset " +
     "mapping is handled for you).",
     {
-      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "resolveJumptable", "pointerTable", "recompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow); recompile = EMIT backend — statically recompile a NES ROM's reset routine to SNES 65816 asar source that builds + boots (phase 1: NROM, 6502→65816 emulation mode, PPU/APU seam STUBBED). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
+      target: z.enum(["bytes", "rom", "project", "references", "cfg", "xrefs", "functions", "decompile", "source", "resolveJumptable", "pointerTable", "recompile"]).describe("bytes = raw chunk; rom = mapper-aware ROM; project = full rebuildable disasm; references = flat da65 operand-refs to an address; functions/cfg/xrefs = Rizin RE engine (function list / control-flow graph / deep graph xrefs); decompile = Ghidra C pseudocode; resolveJumptable = recover a computed-jump dispatcher's targets (LIVE — redirects to breakpoint({on:'jumptable'}), which runs the emulator and records the real switch arms a static decompiler can't follow); recompile = EMIT backend — statically recompile a NES ROM's reset routine to SNES 65816 asar source that builds + boots (phase 1: NROM, 6502→65816 emulation mode, PPU/APU seam STUBBED). See the tool description for the RE loop + the decompile altitude rule + per-CPU quality (all 14 platforms)."),
       // shared
       path: z.string().optional().describe("target=bytes: raw binary path. target=rom/project/references: ROM file path."),
       base64: z.string().optional().describe("target=bytes: base64 of the bytes (OR `path`)."),
-      platform: z.enum(["nes", "snes", "sms", "gg", "gb", "gbc", "atari2600", "atari7800", "c64", "genesis", "gba", "pce", "msx", "lynx"]).optional().describe("target=rom/project/references: override platform (else sniffed from extension)."),
+      platform: z.enum(["nes", "snes", "sms", "gg", "gb", "gbc", "atari2600", "atari7800", "c64", "genesis", "gba", "pce", "msx", "lynx", "pico8"]).optional().describe("target=rom/project/references: override platform (else sniffed from extension). target=source: pico8 (.p8 carts are Lua source)."),
       startAddress: z.number().int().min(0).max(0xffffffff).default(0x8000).describe("target=bytes/rom: address of the first byte (GBA auto-bumped to 0x08000000)."),
       length: z.number().int().min(1).max(65536).optional().describe("target=rom: bytes to disassemble (default 256; mutually exclusive with endAddress)."),
       addOrigin: z.boolean().default(true).describe("target=bytes/rom: prepend `.org` so the asm re-assembles through ca65."),
@@ -1540,6 +1593,7 @@ export function registerDisasmTools(server, z) {
         case "xrefs":      return jsonContent(await analyzeXrefs(requireRomPath(args), args.address, args.platform));
         case "functions":  return jsonContent(await analyzeFunctions(requireRomPath(args), args.platform));
         case "decompile":  return jsonContent(await analyzeDecompile(requireRomPath(args), args.address, args.platform));
+        case "source":     return jsonContent(await readCartSourceCore(args));
         case "recompile":  return await recompileCore(args);
         case "pointerTable": return jsonContent(await pointerTableCore(args));
         case "resolveJumptable":

package/src/mcp/tools/project.js

@@ -662,6 +662,33 @@ const TEMPLATES = {
       mechanics: ["direct framebuffer paint (clear + solid rects)", "recognizable test pattern"],
       techniques: ["PowerVR2 framebuffer bring-up (FB_R_CTRL/FB_R_SIZE/FB_R_SOF1 + SPG)", "640x480 RGB565 at VRAM 0xA5000000", "SH-4 bare crt0 (stack + .bss + main)", "boots on Flycast reios HLE — no firmware"] },
   },
+  // PICO-8 (FAKE-08): the "source" IS a complete .p8 cart (Lua + __gfx__/__sfx__/__music__
+  // sections), so there's no crt0/runtime/linker — fork copies the .p8 and
+  // build({platform:'pico8', source:<the .p8 text>}) packages it. Each is a real playable
+  // game: hand-authored pixel-art sprites, looping music + SFX, title/play/over states,
+  // full genre mechanics. Fork one and reshape a single thing at a time.
+  pico8: {
+    shmup: { main: "templates/shmup.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "STAR SWEEPER — a vertical shooter. Ship sprite w/ thruster animation + i-frame blink, two enemy sprite types, projectile pool, ramping wave spawner, AABB collision, explosion sprites, score + persistent hi-score, looping title/play music that switches on start. The full shmup contract in ~130 lines of Lua.",
+      players: "1", mechanics: ["projectile pool", "wave spawner", "AABB collision", "i-frames", "title/play/over state machine"],
+      techniques: ["hand-authored __gfx__ sprites drawn with spr()", "__music__ + __sfx__ banks (music switches per state)", "sprite animation via frame flip", "scrolling starfield"] },
+    platformer: { main: "templates/platformer.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "HOP QUEST — a platformer. Hero sprite with idle/walk/jump frames (h-flipped by facing), gravity + solid-box collision, variable-height jump, animated spinning-coin sprites to collect, a goal flag, parallax hills, best-time tracking. Fork the movement/level and go.",
+      players: "1", mechanics: ["gravity + solid-box collision", "variable jump", "coin pickups", "goal + win state", "respawn on fall"],
+      techniques: ["hand-authored hero + coin sprites", "spr() h-flip by facing", "walk-cycle animation", "__music__ loop + jump/coin SFX", "parallax backdrop"] },
+    puzzle: { main: "templates/puzzle.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "COLOR DROP — a falling-gem match puzzle. Five faceted gem sprites, an 8×12 well, slide + soft/hard drop, horizontal match-3 line clears with a flash then gravity-settle + combo scoring, next-gem preview, game-over on stack-out. Looping music + drop/slide/match SFX.",
+      players: "1", mechanics: ["grid + falling piece", "match-3 clears", "gravity settle", "combo scoring", "next preview", "stack-out game over"],
+      techniques: ["hand-authored gem sprites", "flash-then-clear timing (state machine on a flash queue)", "column gravity compaction", "__music__ loop + SFX"] },
+    sports: { main: "templates/sports.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "RALLY VOLLEY — a 2-player paddle sports game. Paddle + ball sprites, angle-off-paddle physics, ball speed-up per rally, 1P-vs-CPU (tracking AI) or 2P couch mode toggled on the title, first-to-5 scoring. Looping music + wall/paddle/point SFX. The classic 2P scaffold.",
+      players: "1-2 (vs CPU or couch 2P)", mechanics: ["paddle + ball physics", "angle off paddle", "rally speed-up", "AI opponent", "first-to-5 match"],
+      techniques: ["hand-authored paddle/ball sprites", "mode toggle on title screen", "simple tracking AI", "__music__ loop + bounce/point SFX"] },
+    racing: { main: "templates/racing.p8", runtime: [], lang: "Lua (FAKE-08)", ext: ".p8",
+      describe: "LANE RUNNER — a top-down endless racer. Player + rival car sprites, 3-lane snap-steer dodging, scrolling road with animated lane dashes + shoulders, speed that ramps with distance, screen-shake on crash, distance score + best. Looping engine music + swerve/crash SFX.",
+      players: "1", mechanics: ["lane-snap steering", "rival spawner", "speed ramp", "crash + game over", "distance score"],
+      techniques: ["hand-authored car sprites", "scrolling-road illusion (moving dashes)", "camera() screen-shake", "__music__ loop + SFX"] },
+  },
 };
 // R37: GBC has its own scaffold tree at examples/gbc/templates/ +
 // src/platforms/gbc/lib/c/. Same runtime files as GB (the APU + Z80 +

package/src/toolchains/index.js

@@ -1042,8 +1042,46 @@ export async function buildForPlatform(args) {
     };
   }
 
+  if (args.platform === "pico8") {
+    // PICO-8 "build" = PACKAGE a .p8 cart (plain-text sections), NOT compile to machine
+    // code — the Lua is source. Accept bare Lua (`source`/`lua`) wrapped into a valid .p8,
+    // or a complete .p8 passed through. Optional data sections (gfx/map/sfx/music) via
+    // `sections`. The "binary" IS the .p8 text bytes, which FAKE-08 loads + runs directly.
+    const { packP8 } = await import("./pico8/pack.js");
+    try {
+      const lua = args.lua ?? args.source ?? args.code;
+      const { text, bytes, warnings } = packP8({
+        lua,
+        p8: args.p8,
+        version: args.p8Version,
+        sections: args.sections ?? {},
+      });
+      return {
+        ok: true,
+        binary: bytes,
+        listing: text,      // the readable .p8 IS the listing
+        symbols: "",
+        log: warnings.length ? warnings.map((w) => `[pico8] ${w}`).join("\n") : "[pico8] packaged .p8 cart",
+        issues: [],
+        exitCode: 0,
+        toolchain: "pico8-pack",
+      };
+    } catch (e) {
+      return {
+        ok: false,
+        binary: null,
+        listing: "",
+        symbols: "",
+        log: String(e.message ?? e),
+        issues: [],
+        exitCode: 1,
+        toolchain: "pico8-pack",
+      };
+    }
+  }
+
   throw new Error(
-    `no bundled toolchain for platform '${args.platform}'. Supported: atari2600 (dasm), nes/c64/atari7800/lynx (cc65), snes (C via tcc-65816+wla+PVSnesLib, or asm via asar), genesis (C via m68k-gcc+SGDK, or asm via vasm68k), gba (C via arm-gcc+libtonc/libgba), gb/gbc (sdcc sm83 / rgbds), sms/gg (sdcc). Call listPlatforms for the live matrix.`,
+    `no bundled toolchain for platform '${args.platform}'. Supported: atari2600 (dasm), nes/c64/atari7800/lynx (cc65), snes (C via tcc-65816+wla+PVSnesLib, or asm via asar), genesis (C via m68k-gcc+SGDK, or asm via vasm68k), gba (C via arm-gcc+libtonc/libgba), gb/gbc (sdcc sm83 / rgbds), sms/gg (sdcc), pico8 (.p8 cart packager). Call listPlatforms for the live matrix.`,
   );
 }
 

package/src/toolchains/pico8/pack.js

@@ -0,0 +1,67 @@
+// PICO-8 .p8 cart "builder" — a PACKAGER, not a compiler. PICO-8 carts are plain-text
+// files with labeled sections (__lua__, __gfx__, __gff__, __label__, __map__, __sfx__,
+// __music__); the Lua is source, not machine code. So "build" here = assemble a valid
+// .p8 from the given Lua (+ optional data sections) that FAKE-08 can load and run.
+//
+// Accepts either a full .p8 already (passed through / validated) or bare Lua source
+// (wrapped into a minimal but valid .p8). Data sections can be supplied verbatim.
+
+const P8_HEADER = "pico-8 cartridge // http://www.pico-8.com";
+const KNOWN_SECTIONS = ["lua", "gfx", "gff", "label", "map", "sfx", "music"];
+
+/** Is this text already a full .p8 cart (has the header + a __lua__ section)? */
+export function isP8Cart(text) {
+  return /^pico-8 cartridge/i.test(text.trimStart()) && /(^|\n)__lua__/.test(text);
+}
+
+/**
+ * Assemble a .p8 cart.
+ * @param {object} opts
+ * @param {string} opts.lua         Lua source for the __lua__ section (required unless `p8` given).
+ * @param {string} [opts.p8]        A complete .p8 already — validated + passed through.
+ * @param {number} [opts.version]   PICO-8 format version line (default 18).
+ * @param {Object<string,string>} [opts.sections]  Extra sections by name → body text
+ *        (e.g. { gfx: "...", map: "...", sfx: "...", music: "..." }). Bodies are the raw
+ *        hex/number rows PICO-8 uses; passed through verbatim.
+ * @returns {{ text: string, bytes: Uint8Array, warnings: string[] }}
+ */
+export function packP8({ lua, p8, version = 18, sections = {} } = {}) {
+  const warnings = [];
+
+  if (p8 != null) {
+    if (!isP8Cart(p8)) {
+      throw new Error("pico8 build: `p8` was given but doesn't look like a .p8 cart (missing 'pico-8 cartridge' header or __lua__ section).");
+    }
+    const text = p8.endsWith("\n") ? p8 : p8 + "\n";
+    return { text, bytes: new TextEncoder().encode(text), warnings };
+  }
+
+  if (typeof lua !== "string" || lua.trim() === "") {
+    throw new Error("pico8 build: provide `lua` (the cart's Lua source) or a full `p8`.");
+  }
+
+  // Validate any extra section names.
+  for (const name of Object.keys(sections)) {
+    if (!KNOWN_SECTIONS.includes(name)) {
+      warnings.push(`unknown .p8 section '__${name}__' — passing through, but PICO-8/FAKE-08 may ignore it.`);
+    }
+  }
+
+  const parts = [P8_HEADER, `version ${version}`, "__lua__", lua.replace(/\n$/, "")];
+  // Emit data sections in canonical order (skip __lua__, handled above).
+  for (const name of KNOWN_SECTIONS) {
+    if (name === "lua") continue;
+    if (sections[name] != null) {
+      parts.push(`__${name}__`, String(sections[name]).replace(/\n$/, ""));
+    }
+  }
+  // Pass through any unknown sections last (so nothing the caller sent is dropped).
+  for (const [name, body] of Object.entries(sections)) {
+    if (!KNOWN_SECTIONS.includes(name)) {
+      parts.push(`__${name}__`, String(body).replace(/\n$/, ""));
+    }
+  }
+
+  const text = parts.join("\n") + "\n";
+  return { text, bytes: new TextEncoder().encode(text), warnings };
+}