romdevtools 0.85.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/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.86.0 — 2026-07-01
+
+- **GameTank Game Genie — a brand-new cheat-code format.** Nobody had made GameTank cheat codes
+  before; this adds a Game-Genie-style read-substitution device to the emulated GameTank core plus
+  a code format that is HARDWARE-COMPATIBLE (the same codes would work on a physical Game Genie
+  built for the console's open cart bus).
+  - Core (`romdev-core-gametank@0.2.0`): a value-override cheat device in the shared debug lib
+    (`romdev_cheat_set`/`romdev_cheat_read`/`romdev_cheat_get`, 24 slots). `MemoryRead` returns the
+    substitute byte on an address match, with optional compare-against-original (survives bank
+    switching) — exactly what a hardware Game Genie does. Any core that adds the one-line
+    `romdev_cheat_read` call to its bus read gets this for free.
+  - Format: `encodeGameTankGameGenie`/`decodeGameTankGameGenie` — a distinct 16-letter wheel
+    (`KLMNPQRSTVWXYZ23`), 16-bit address + 8-bit value (+ optional compare), scrambled with a
+    checksum. Plain codes are `XXX-XXXX`, compare codes `XXXX-XXXXX` (e.g. `$8100→0x42` = KTM-LPK3).
+    Wired into every device dispatcher; `cheats({op:'make', platform:'gametank', …})` generates
+    codes and `cheats({op:'apply'})` applies them live. GameTank's `retro_cheat_set` is a stub, so
+    `LibretroHost.setCheat` routes GameTank cheats through the romdev value-override device.
+- **jsgame test no longer skips.** It ran only under `--experimental-vm-modules`, so the default
+  suite skipped it. It now runs in an isolated forked child process (SDL is main-thread-only;
+  rungame leaks handles) driven over rawr JSON-RPC — the child carries the flag and is killed when
+  the RPC resolves, so the main suite stays clean. Suite: 1099 tests, 1099 pass, 0 skipped.
+
 ## 0.85.0 — 2026-07-01
 
 - **Native-runtime game kinds — wasmcart + jsgame are now first-class hosts.** romdev is a

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