romdevtools 0.14.0 → 0.16.0

package/AGENTS.md

@@ -43,7 +43,7 @@ Skip playtest only when there's clearly no human in the loop: CI runs, automated
 
 ## Tool surface: everything is loaded — just call the tool
 
-**All ~34 tools are registered and callable from session init — there is no loading step.** If you see a tool name anywhere in this doc or via `catalog({op:'categories'})`, you can call it right now. Each tool is a small VERB with an operation axis — `memory({op})`, `build({output})`, `sprites({op})`, `breakpoint({on})`, `cpu({op})` — so the whole surface is a few dozen names, not a few hundred.
+**All ~32 tools are registered and callable from session init — there is no loading step.** If you see a tool name anywhere in this doc or via `catalog({op:'categories'})`, you can call it right now. Each tool is a small VERB with an operation axis — `memory({op})`, `build({output})`, `sprites({op})`, `breakpoint({on})`, `cpu({op})` — so the whole surface is a few dozen names, not a few hundred.
 
 (We used to lazy-load tools behind a `loadCategory` call. It caused more harm than good — agents burned round-trips re-loading categories, and dynamic registration never propagated reliably to clients anyway. The consolidation shrank the surface enough that the entire thing loads up front; the old `loadCategory`/`describeTool` discovery tools are gone.)
 
@@ -242,14 +242,21 @@ your project dir, it lands at `./read_joystick.asm` (alongside
 `main.asm`), NOT under `./include/` or `./lib/`. Every platform
 follows the same flat layout.
 
-Because the layout is flat, **`build({output:'project', path, platform})` rebuilds the
-whole directory in one call — no per-iteration file manifest.** It finds `main.c`
-(C / SGDK Genesis / GBA / cc65-C / SDCC-C) or `main.s` / `main.asm` (asm), links every
-`.c`/`.s` in the dir, treats `.h`/`.inc` as includes, and folds binary assets
-(`.bin/.chr/.pcm/.brr/.vgm/...`) in as `binaryIncludes`. So iterating an on-disk project is
-just `build({output:'project', path:'/my/proj', platform})` every time — you don't re-send
-`sources`/`includes` each build. (Use `build({output:'rom'})` with explicit `sources` when
-the files aren't on disk, e.g. generated in-context.)
+Because the layout is flat, **the simplest loop is `build({output:'run', path, platform})`
+(build + load + run + screenshot in one call) or `build({output:'project', path, platform})`
+(build the dir to a ROM) — no per-iteration file manifest, on EVERY platform.** Point it at
+a scaffolded directory and it does the right per-platform thing automatically: finds the
+entry (`main.c` for C / SGDK Genesis / GBA / cc65-C / SDCC-C, or `main.s` / `main.asm` for
+asm), routes the platform's crt0 correctly (e.g. GB/GBC `gb_crt0.s` via the cart-header path,
+not as a plain source — so no `gsinit` collision), applies the right linker preset
+(e.g. NES `chr-ram-runtime`, which supplies the OAM/CHARS segments), skips SDK intermediates
+(e.g. Genesis `sega.preprocessed.s`, the SNES SPC700 driver, any `*.upstream.*`), wires the
+runtime (GBA libtonc/libgba/maxmod by what the source includes), routes `#include`d C/asm
+siblings as includes, treats `.h`/`.inc` as includes, and folds binary assets
+(`.bin/.chr/.pcm/.brr/.vgm/.xgc/...`) in as `binaryIncludes`. So iterating an on-disk project
+is just `build({output:'run', path:'/my/proj', platform})` every time — you do **not** need to
+enumerate `sources`/`includes`/`crt0Path`/`linkerConfig` by hand. (Use `build({output:'rom'})`
+with explicit `sources` only when the files aren't on disk, e.g. generated in-context.)
 
 ## Supported platforms
 
@@ -881,7 +888,7 @@ OAM format: bytes per sprite are `[y, tileIndex, attributes, x]`.
 
 Three shapes, pick the one that matches what you're doing:
 
-- **`scaffold({op:'project', platform, name, path, template?})`** — writes a starter directory: `main.{c,asm,s}` (from `examples/<platform>/templates/`) + every runtime file the template depends on (headers, crt0, linker .cfg) + README + `.gitignore`. Self-contained: take it elsewhere and rebuild with stock cc65/sdcc, no romdev install needed. Defaults to `template:"default"` (smallest visible-and-runnable program); most tier-1 platforms also have `hello_sprite` + `tile_engine` + the 5 genre templates.
+- **`scaffold({op:'project', platform, name, path, template?})`** — writes a starter directory: `main.{c,asm,s}` (from `examples/<platform>/templates/`) + every runtime file the template depends on (headers, crt0, linker .cfg) + README + `.gitignore`. Self-contained: take it elsewhere and rebuild with stock cc65/sdcc, no romdev install needed. Defaults to `template:"default"` (smallest visible-and-runnable program); most tier-1 platforms also have `hello_sprite` + `tile_engine` + the 5 genre templates. **Then build it in ONE call: `build({output:'run', path:<that dir>, platform})`** — the dir build applies the platform's recipe (crt0/linker-preset/runtime/intermediate-skip) automatically, so you never hand-wire `crt0Path`/`codeLoc`/`linkerConfig`. This scaffold→build path is verified to build + render on every platform/template.
 
 - **`scaffold({op:'project', ..., withSnippets: true})`** — same as above, **plus** drops every vetted starter snippet for the platform alongside main.c. Use when you want "main.c + every helper file ready to edit" in one shot, without picking a genre. Snippets that overlap with the template's runtime are skipped (no double-writes). Response includes `snippetsCopied: string[]`.
 
@@ -1044,7 +1051,7 @@ A few platform-tool quirks worth knowing up front:
 - **asar bank-border-crossed** can happen if your `org` + `dw` runs past $00FFFF. Native vectors are at $FFE4-$FFEE; emulation vectors at $FFF4-$FFFF. Use `scaffold({op:'snippets', platform: "snes", mode: "get", name: "lorom_header.asm"})` for the layout.
 - **cc65 (NES, C64, etc.) zero page** starts at $02. cc65 reserves $00-$01 for its runtime. Your first `.res 1` lands at $02, not $00. Use `symbols({op:'map'})` after `build({output:'romWithDebug'})` to confirm.
 - **NES pattern table cap = 256 tiles per nametable**. The tilemap index is 8-bit, so per-frame BG can use at most 256 unique tiles per pattern table. Auto-converting a busy illustration usually overflows. `encodeArt({stage:'tilemap'})` warns; the only workaround is mid-frame CHR bank switching (MMC3-class mapper).
-- **NES + GB/GBC turnkey** (R9/R10 self-contained + sound, 2026-05-25): use `scaffold({op:'project', platform, template, name, path})` to scaffold a project. The pipeline copies every file the template depends on — `{nes,gb}_runtime.{h,c}`, `gb_hardware.h`, custom `crt0.s`, linker `.cfg`, `patch-header.js` (GB) — into the project directory alongside `main.c`. **No auto-injection at build time.** The build pipeline compiles exactly what you tell it via `sources` / `sourcesPaths` / `includes` / `includePaths` / `crt0` / `crt0Path` / `linkerConfig` / `codeLoc`. Take the project elsewhere with stock cc65/sdcc and it builds the same way. The runtime APIs include sprites, BG, input, AND **sound** — `sound_init` / `sound_play_tone(channel, period, vol, length)` / `sound_play_noise` / `sound_off`. NES drives pulse1+pulse2+triangle+noise via $4000-$400F + $4015; GB drives the 4-channel APU via NR10-NR52. SFX-grade, fire-and-forget — for full music tracks, drop in famitone2 (NES) or your own driver. Templates: `default` (palette cycle), `hello_sprite` (sprite + d-pad + **beep on A press**), `tile_engine` (multi-room tile map). Docs: [`src/platforms/nes/MENTAL_MODEL.md`](src/platforms/nes/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/nes/TROUBLESHOOTING.md); [`src/platforms/gb/MENTAL_MODEL.md`](src/platforms/gb/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/gb/TROUBLESHOOTING.md). **Game-loop order matters on NES:** stage `oam_clear`+`oam_spr` BEFORE `ppu_wait_nmi`, not after — the NMI handler DMA's whatever shadow_oam contains at vblank-start. **GB ROM header:** both asm and C builds now auto-run `rgbfix` inside `build({output:'rom'})`, so the Nintendo logo + checksums + CGB flag are correct out of the box — no manual header-patch step needed (use `romPatch({op:'gbHeader'})` only to fix up an external ROM).
+- **NES + GB/GBC turnkey** (R9/R10 self-contained + sound, 2026-05-25): use `scaffold({op:'project', platform, template, name, path})` to scaffold a project. The pipeline copies every file the template depends on — `{nes,gb}_runtime.{h,c}`, `gb_hardware.h`, custom `crt0.s`, linker `.cfg`, `patch-header.js` (GB) — into the project directory alongside `main.c`. **No auto-injection at build time.** Iterate the whole dir in one call with `build({output:'run', path, platform})` (or supply `sources` / `sourcesPaths` / `includes` / `includePaths` / `crt0` / `crt0Path` / `linkerConfig` / `codeLoc` explicitly when the files aren't on disk). Take the project elsewhere with stock cc65/sdcc and it builds the same way. The runtime APIs include sprites, BG, input, AND **sound** — `sound_init` / `sound_play_tone(channel, period, vol, length)` / `sound_play_noise` / `sound_off`. NES drives pulse1+pulse2+triangle+noise via $4000-$400F + $4015; GB drives the 4-channel APU via NR10-NR52. SFX-grade, fire-and-forget — for full music tracks, drop in famitone2 (NES) or your own driver. Templates: `default` (palette cycle), `hello_sprite` (sprite + d-pad + **beep on A press**), `tile_engine` (multi-room tile map). Docs: [`src/platforms/nes/MENTAL_MODEL.md`](src/platforms/nes/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/nes/TROUBLESHOOTING.md); [`src/platforms/gb/MENTAL_MODEL.md`](src/platforms/gb/MENTAL_MODEL.md) + [`TROUBLESHOOTING.md`](src/platforms/gb/TROUBLESHOOTING.md). **NES sprite staging:** the bundled `nes_runtime` now handles the OAM-DMA race for you (oam_clear just resets the index; ppu_wait_nmi hides unused slots after you stage), so the old "must stage before ppu_wait_nmi" flicker trap is gone — the standard `oam_clear → oam_spr → ppu_wait_nmi` loop renders cleanly. **GB ROM header:** both asm and C builds auto-run `rgbfix` inside `build({output:'rom'/'run'})`, so the Nintendo logo + checksums + CGB flag are correct out of the box — no manual header-patch step needed (use `romPatch({op:'gbHeader'})` only to fix up an external ROM).
 - **Game Boy / GBC silent-failure footguns** (R54 cleanup, full detail in `platform({op:'doc', platform:"gb"|"gbc", name:"mental_model"})`):
   - **The bundled `gb_crt0.s` is now actually linked.** Pre-r54 a fundamental bug in `buildZ80C` was shipping the raw .s text to sdld as if pre-assembled — sdld silently rejected it and fell back to SDCC's stock sm83 crt0 (no GB cart boot, no IRQ vectors). Map showed no `init` symbol, $0000 was $FF, $0100 was $FF. Every GB ROM ran on stock crt0 invisibly. Fixed by auto-detecting .s source vs .rel object and running it through sdasgb first. Post-fix: `init` at $0150, entry $0100 = `00 c3 50 01` (nop; jp $0150), reset vector $0000 = $C9. **This was the root cause for #14 audio AND part of why every previous "runtime should work OOTB" round still felt friction-heavy.**
   - **GB/GBC C builds now auto-fix the header at build time** (rgbfix runs inside `build({output:'rom'})`): Nintendo logo at $0104, header checksum at $014D, global checksum, and the CGB flag at $0143 ($00 for `.gb`, $C0 for `.gbc`). You no longer need to patch the header manually — the ROM `build({output:'rom'})` hands back boots on real hardware as-is. `romPatch({op:'gbHeader', path})` still exists if you want to override title / cart type / RAM size / etc. on an existing file.

package/CHANGELOG.md

@@ -4,6 +4,100 @@ 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.15.0
+
+**Scaffold audit: every scaffold on every platform now builds AND renders.** Two
+independent multi-agent audits found the documented "scaffold then build the dir"
+happy path was broken on most platforms, and that many scaffolds built but
+rendered blank. Both are fixed — verified 115/115 templates build via the dir
+path, and every genre game renders recognizable content. This matters most for
+weaker agents: the first build now succeeds, so they build on a working example
+instead of assuming the server is broken and installing their own tools.
+
+### Fixed — project-directory build (the linchpin)
+- **`build({output:'run'|'project', path})` now works on EVERY platform.** It was
+  0/8 on GB/GBC/NES/Genesis and 0/5 on Atari 2600 via the natural path. The
+  dir-builder used to glob every file as a source; it now applies a per-platform
+  recipe that matches a hand-written build: routes the crt0 correctly (GB/GBC
+  `gb_crt0.s` via the cart-header path — no more `Multiple definition of gsinit`),
+  applies the linker preset (NES `chr-ram-runtime` — no more `Missing memory area
+  'OAM'`), skips SDK intermediates (Genesis `sega.preprocessed.s`, the SNES SPC700
+  driver, any `*.upstream.*`), wires the GBA runtime (libtonc/libgba/maxmod by
+  what the source includes), routes `#include`d C/asm siblings as includes, and
+  bundles every incbin asset (`.xgc`/`.vgz`/…). `output:'run'` accepts `path` too
+  (build+load+run+screenshot a dir in one call). One shared code path so the two
+  build routes can't drift. Locked in by `scaffold-build-happypath.test.js`.
+- **SNES multi-`.c` builds** (genre scaffolds ship `main.c` + `snes_sfx.c`) — the
+  stale single-`.c` guard in `buildSnesC` is removed (the link path already
+  handled multiple TUs).
+
+### Fixed — scaffolds rendered blank/wrong (now show content)
+- **SMS/GG**: `vdp_init` R6 default 0xFB→0xFF — sprite tiles now read from $2000
+  where scaffolds upload them (were reading the empty $0000 bank → invisible). GG
+  also: 64-byte GG palette format (scaffolds shipped 32) + visible-window coords.
+- **Genesis**: genre scaffolds now call `VDP_linkSprites` (the SAT link bytes were
+  0 = end-of-list → only slot 0 drew); shmup enemies spread across the field.
+- **SNES**: `sports`/`racing` `oamSet` now uses byte offsets (`slot<<2`); a real
+  4bpp console font is embedded (the stub made all text black) + the BG-base /
+  text-offset / `consoleVblank` wiring fixed → c_hello/puzzle/platformer show text.
+- **Lynx**: `platformer`/`puzzle`/`sports`/`racing` use the `while(tgi_busy()){}` +
+  full-screen `tgi_bar` clear (were black via bare `tgi_clear()`).
+- **C64**: genre sprite data moved $0800→$2000 (it collided with the $0801 `.prg`
+  load → `sports` crashed to BASIC, sprites corrupt).
+- **NES**: the bundled runtime no longer races the OAM-DMA — `oam_clear` resets the
+  index and `ppu_wait_nmi` hides unused slots after staging, so sprite-light
+  scaffolds no longer flicker to black; `default` backdrop no longer cycles to black.
+- **PCE**: `pce_video.c` now programs the VDC display timing (NTSC 256×224) — fixes
+  the vertically-doubled picture.
+- **GBA**: per-frame `tte_printf("%05d")` (broken in the bundled libtonc — garbles +
+  wedges the loop) replaced with a hand-built score string + `tte_write`.
+- **Atari 2600**: `paddle` kernel rebuilt to a 2-line kernel (the per-line work
+  overflowed a 76-cycle scanline → ~250 lines, no vsync lock); now stable at 210.
+
+### Changed
+- **Doc-drift swept**: every agent-facing `runSource`/`buildSource` → the current
+  `build({output:'run'|'rom'})`, dead tool names (`loadCategory`, `inspectSprites`,
+  …) → the consolidated forms, across the scaffold README emitter, `nextStep`,
+  examples, platform docs, and `.cfg` comments. Emitted scaffold-README `frames`
+  60→240 (60 caught the boot logo on some platforms → false "blank").
+- **Thin genres** given a BG world (Genesis sports court / racing road, NES racing
+  road, SNES sports/racing) so they read as the genre, not objects on black.
+- **Missing-genre error** for msx/pce/atari2600 now names the working project
+  templates instead of a bare "default".
+- The `uint8-loop-bound` preflight lint is scope-aware (no longer false-flags a
+  `uint16_t` loop counter that shares a name with a `uint8_t` in another function).
+
+## 0.16.0
+
+**Build diagnostics: agents were building blind — errors AND warnings now reach
+the response as structured `issues[]`.** An agent can only fix what the toolchain
+tells it, where it tells it. Audited the whole build surface and closed the gaps
+so diagnostics (file/line/message/stage) come back in the tool result, not buried
+in the raw log. (Also bumps a doc count: the surface is 32 tools after 0.15.0's
+dmaTrace→watch / patchGbHeader→romPatch consolidation; stale "34" references in
+the docs + source comments updated.)
+
+### Fixed
+- **Warnings were OFF.** No C compiler was being asked for them. gcc (GBA/Genesis)
+  now compiles USER source with `-Wall -Wextra -Wno-unused-parameter` (the bundled
+  SDK stays warning-free so its noise doesn't bury the agent's); cc65 enables its
+  valid high-value `-W` set. So unused vars, implicit declarations, etc. are now
+  emitted and surfaced.
+- **Swallowed errors now structured:** SDCC's keyword-less `file:line: syntax
+  error: …` and `warning NNN: …` (GB/GBC/SMS/MSX previously returned an empty
+  `issues[]` on a syntax error); the sdld/ASlink `Undefined Global '_x'` link
+  error; vasm errors (Genesis asm emits no stage marker, so they hit the
+  fallback, which had skipped the vasm parser); and a **missing `incbin` asset**
+  — the #1 thing an agent forgets to pass — now reports `could not open <x.bin>`
+  with the exact filename.
+- **Fixed a build crash that ate the real error:** `build({output:'rom', path})`
+  fell into the source builder with no source and threw "Cannot read properties
+  of undefined (reading 'split')" instead of the compiler error; it now routes to
+  the project-dir builder like `output:'run'`/`'project'`.
+- Verified live across all 14 platforms; a `parse-errors-coverage` test locks the
+  formats in. (Known limit: asar/SNES-asm only yields a wrapper "aborted"
+  message — its WASM build aborts without printing line info.)
+
 ## 0.14.0
 
 **Two platform-specific top-level tools folded into their domain verbs, a

package/README.md

@@ -52,7 +52,7 @@ Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instru
 Most agents support MCP, but you don't have to use it. Run the server
 (`npx romdevtools`) and **skip wiring it into your agent's MCP
 config** — no `claude mcp add`, no `mcp.json` entry, no MCP client at all. The
-same 34 tools are reachable over plain HTTP / as an Agent Skill against the
+same 32 tools are reachable over plain HTTP / as an Agent Skill against the
 running server:
 
 - **Plain HTTP:** `POST http://127.0.0.1:7331/tool/{name}` with the args as a JSON

package/examples/atari2600/main.asm

@@ -3,7 +3,7 @@
 ; standard NTSC frame timing (3 vsync + 37 vblank + 192 visible + 30
 ; overscan). Read joystick to move the sprite.
 ;
-; Build: buildSource({ platform: "atari2600", source: <this file> })
+; Build: build({ output: "rom",  platform: "atari2600", source: <this file> })
 
   processor 6502
   org $F000

package/examples/atari2600/templates/default.asm

@@ -3,7 +3,7 @@
 ; standard NTSC frame timing (3 vsync + 37 vblank + 192 visible + 30
 ; overscan). Read joystick to move the sprite.
 ;
-; Build: buildSource({ platform: "atari2600", source: <this file> })
+; Build: build({ output: "rom",  platform: "atari2600", source: <this file> })
 
   processor 6502
   org $F000

package/examples/atari2600/templates/paddle.asm

@@ -111,9 +111,14 @@ MAIN:
   STA VSYNC
 
   ; ── VBLANK (37 lines) — game logic ────────────────────────────────
+  ; 34 here + the 3 STA WSYNC in the P0/P1 positioning block below = 37 VBLANK
+  ; lines total. (Bug fix: this loop used to be 37 AND the positioning added 3
+  ; more → 265 scanlines/frame → the TV/emulator can't lock vsync → rolling /
+  ; black picture. Exactly 262 lines = 3 VSYNC + 37 VBLANK + 192 visible + 30
+  ; overscan; the positioning WSYNCs MUST be counted against the 37.)
   LDA #2
   STA VBLANK
-  LDX #37
+  LDX #34
 .vb:
   STA WSYNC
   DEX
@@ -212,93 +217,100 @@ MAIN:
   STA AUDV0
 .sfx_done:
 
-  ; Position P0 horizontally at column 16 (race-the-beam delay)
-  STA WSYNC
-  LDA #1
+  ; ── Position P0 / P1 / HMOVE — exactly 3 WSYNC-bounded lines ───────
+  ; CRITICAL: every RESPx write AND the STA HMOVE must complete inside
+  ; the 76-cycle scanline that began with its STA WSYNC. A DEX/BNE delay
+  ; loop costs 5 cycles/iteration, so the loop count must be small enough
+  ; that RESPx still lands before the line ends. The old code used
+  ; LDX #38 (~189 cycles = 2.5 scanlines!) with no WSYNC before RESP1/
+  ; HMOVE, so it emitted ~2-3 UNCOUNTED scanlines past the 262 budget →
+  ; ~265 lines/frame → vsync never locks (rolling magenta band). HMOVE
+  ; was also issued mid-line; it must follow a fresh WSYNC.
+
+  ; Line 1 of 3: coarse-position P0 (left, ~column 16)
   STA WSYNC
-  LDX #15
+  LDX #5
 .p0d:
   DEX
-  BNE .p0d
+  BNE .p0d           ; ~24 cycles in → P0 lands near the left edge
   STA RESP0
-  ; Position P1 at column 144
+  ; Line 2 of 3: coarse-position P1 (right, ~column 132)
   STA WSYNC
-  LDX #38
+  LDX #13
 .p1d:
   DEX
-  BNE .p1d
+  BNE .p1d           ; ~64 cycles in (< 76) → P1 lands near the right
   STA RESP1
+  ; Line 3 of 3: apply HMOVE on a FRESH line, right after WSYNC
+  STA WSYNC
   STA HMOVE
 
   LDA #0
   STA VBLANK
 
-  ; ── Visible (192 lines) ───────────────────────────────────────────
+  ; ── Visible (192 lines) — TWO-LINE KERNEL ─────────────────────────
+  ; CRITICAL: a single scanline is only 76 CPU cycles. The full per-line
+  ; render here (playfield walls + P0 + P1 + ball, each a SEC/SBC/CMP +
+  ; conditional store) is ~88 cycles — it does NOT fit in one line. In a
+  ; 1-line kernel each WSYNC iteration then spills past the line boundary,
+  ; so 192 iterations stretch to ~232 emitted lines → ~250-line frame →
+  ; vsync never locks (rolling magenta band — THE bug).
+  ;
+  ; The fix is the standard 2600 "2-line kernel": each loop pass renders
+  ; TWO scanlines and splits the work across two WSYNCs, doubling the
+  ; budget to ~152 cycles. 96 passes × 2 lines = 192 visible lines.
+  ; Y counts 192→2 in steps of 2; paddles/ball move in 2px steps (fine
+  ; for Pong). The branchless "LDA #off / CMP / BCS skip / LDA #on" form
+  ; also drops the JMPs the old code paid every line.
   LDY #192
 .draw:
+  ; ---- first line of the pair: playfield walls + left paddle ----
   STA WSYNC
-  TYA
-  ; Top-bottom walls: lines 0..3 and 188..191 draw a full-width PF
-  CMP #4
-  BCS .nottop
-  LDA #$FF
-  STA PF0
-  STA PF1
-  STA PF2
-  JMP .pf_done
-.nottop:
-  CMP #188
-  BCC .notbot
-  LDA #$FF
-  STA PF0
-  STA PF1
-  STA PF2
-  JMP .pf_done
-.notbot:
+  ; Top + bottom walls: full-width PF on the outer rows (Y>=189 / Y<5)
   LDA #0
+  CPY #189
+  BCS .wall
+  CPY #5
+  BCS .nowall
+.wall:
+  LDA #$FF
+.nowall:
   STA PF0
   STA PF1
   STA PF2
-.pf_done:
   ; Left paddle: 8 lines starting at P0_Y
   TYA
   SEC
   SBC P0_Y
   CMP #8
-  BCS .p0blank
-  LDA #$FF
-  STA GRP0
-  JMP .p0done
-.p0blank:
   LDA #0
+  BCS .p0off
+  LDA #$FF
+.p0off:
   STA GRP0
-.p0done:
+  ; ---- second line of the pair: right paddle + ball ----
+  STA WSYNC
   ; Right paddle: 8 lines starting at P1_Y
   TYA
   SEC
   SBC P1_Y
   CMP #8
-  BCS .p1blank
-  LDA #$FF
-  STA GRP1
-  JMP .p1done
-.p1blank:
   LDA #0
+  BCS .p1off
+  LDA #$FF
+.p1off:
   STA GRP1
-.p1done:
   ; Ball: 2 lines starting at BALL_Y
   TYA
   SEC
   SBC BALL_Y
   CMP #2
-  BCS .blblank
-  LDA #2
-  STA ENABL
-  JMP .bldone
-.blblank:
   LDA #0
+  BCS .bloff
+  LDA #2
+.bloff:
   STA ENABL
-.bldone:
+  DEY
   DEY
   BNE .draw
 

package/examples/atari7800/main.c

@@ -1,6 +1,6 @@
 // ── Hello, Atari 7800 — MARIA bring-up + single sprite ──────────────
 //
-// Build: buildSource({ platform: "atari7800", source: <this file>,
+// Build: build({ output: "rom",  platform: "atari7800", source: <this file>,
 //                      language: "c" })
 //
 // Sets up a minimal display list, paints the background blue and renders

package/examples/atari7800/templates/default.c

@@ -34,7 +34,7 @@
  * the 4KB of internal RAM.
  *
  * ── Build ───────────────────────────────────────────────────────
- *   buildSource({ platform: "atari7800", sources: { "main.c": ... } })
+ *   build({ output: "rom",  platform: "atari7800", sources: { "main.c": ... } })
  */
 #include <stdint.h>
 #include "atari7800_sfx.h"

package/examples/atari7800/templates/music_demo.c

@@ -10,7 +10,7 @@
  *
  * The note tables live in atari7800_music.c — they ARE the song.
  *
- * Build: buildSource({ platform: "atari7800", template: "music_demo" })
+ * Build: build({ output: "rom",  platform: "atari7800", template: "music_demo" })
  */
 #include <stdint.h>
 #include "atari7800_music.h"

package/examples/c64/main.c

@@ -4,7 +4,7 @@
 // directly: writes screen codes into screen RAM, sets per-cell colors
 // in color RAM, and cycles the border color in a main loop.
 //
-// Build: buildSource({ platform: "c64", source: <this file>, language: "c" })
+// Build: build({ output: "rom",  platform: "c64", source: <this file>, language: "c" })
 
 #include <stdint.h>
 

package/examples/c64/templates/platformer.c

@@ -80,7 +80,7 @@ static void wait_vblank(void) {
 
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
-  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
   for (i = 0; i < 64; i++) dst[i] = data[i];
 }
 
@@ -131,7 +131,7 @@ void main(void) {
 
   POKE(VIC_SPR_ENA, 0);
   copy_sprite(0, player_sprite);
-  SPRITE_POINTERS[0] = 0x20;
+  SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
   POKE(VIC_SPR_COL(0), 0x07);  /* yellow player */
   POKE(VIC_BORDER, 0x06);      /* dark blue */
   POKE(VIC_BG0,    0x06);

package/examples/c64/templates/puzzle.c

@@ -121,7 +121,7 @@ static void lock_piece(void) {
         grid[r][c] = 0;
         grid[r][c+1] = 0;
         grid[r][c+2] = 0;
-        if (score < 65500) score += 30;
+        if (score < 65500u) score += 30;
         sfx_tone(0, 0x80, 0x10, 12);
       }
     }

package/examples/c64/templates/racing.c

@@ -49,7 +49,7 @@ static void wait_vblank(void) {
 
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
-  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
   for (i = 0; i < 64; i++) dst[i] = data[i];
 }
 
@@ -75,8 +75,8 @@ void main(void) {
   uint8_t i, pad;
   POKE(VIC_SPR_ENA, 0);
   copy_sprite(0, car_sprite);
-  SPRITE_POINTERS[0] = 0x20;
-  for (i = 0; i < MAX_OBS; i++) SPRITE_POINTERS[1 + i] = 0x20;
+  SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
+  for (i = 0; i < MAX_OBS; i++) SPRITE_POINTERS[1 + i] = 0x80;
   POKE(VIC_SPR_COL(0), 0x07);  /* yellow player */
   for (i = 0; i < MAX_OBS; i++) POKE(VIC_SPR_COL(1 + i), 0x02);  /* red obstacles */
   POKE(VIC_BORDER, 0x00);

package/examples/c64/templates/shmup.c

@@ -20,7 +20,8 @@
 #define PEEK(addr)      (*(volatile uint8_t*)(addr))
 
 #define SPRITE_POINTERS  ((volatile uint8_t*)0x07F8)
-#define SPRITE_DATA_BASE 0x0800  /* sprite N data at $0800 + N*64 */
+#define SPRITE_DATA_BASE 0x2000  /* sprite N data at $2000 + N*64 — NOT $0800,
+                                  * which collides with the $0801 .prg load (C64-1) */
 
 #define JOY_UP    0x01
 #define JOY_DOWN  0x02
@@ -121,9 +122,9 @@ void main(void) {
 
   /* Sprite pointers: slot N points at /64 index into the VIC bank.
    * Default bank = $0000-$3FFF. $0800 / 64 = 32 = $20. */
-  SPRITE_POINTERS[SLOT_PLAYER] = 0x20;
-  for (i = 0; i < MAX_BULLETS; i++) SPRITE_POINTERS[SLOT_BULLET0 + i] = 0x21;
-  for (i = 0; i < MAX_ENEMIES; i++) SPRITE_POINTERS[SLOT_ENEMY0 + i] = 0x22;
+  SPRITE_POINTERS[SLOT_PLAYER] = 0x80;  /* $2000/64 */
+  for (i = 0; i < MAX_BULLETS; i++) SPRITE_POINTERS[SLOT_BULLET0 + i] = 0x81;
+  for (i = 0; i < MAX_ENEMIES; i++) SPRITE_POINTERS[SLOT_ENEMY0 + i] = 0x82;
 
   POKE(VIC_SPR_COL(SLOT_PLAYER), 0x07);  /* yellow */
   for (i = 0; i < MAX_BULLETS; i++) POKE(VIC_SPR_COL(SLOT_BULLET0 + i), 0x01);  /* white */
@@ -175,7 +176,7 @@ void main(void) {
         if (aabb(&bullets[i], &enemies[j])) {
           bullets[i].alive = 0;
           enemies[j].alive = 0;
-          if (score < 65500) score += 10;
+          if (score < 65500u) score += 10;
           sfx_noise(8);
           break;
         }

package/examples/c64/templates/sports.c

@@ -41,7 +41,7 @@ static void wait_vblank(void) {
 
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
-  volatile uint8_t *dst = (volatile uint8_t*)(0x0800 + slot * 64);
+  volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
   for (i = 0; i < 64; i++) dst[i] = data[i];
 }
 
@@ -56,9 +56,9 @@ void main(void) {
   copy_sprite(0, paddle_sprite);
   copy_sprite(1, paddle_sprite);
   copy_sprite(2, ball_sprite);
-  SPRITE_POINTERS[0] = 0x20;
-  SPRITE_POINTERS[1] = 0x21;
-  SPRITE_POINTERS[2] = 0x22;
+  SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
+  SPRITE_POINTERS[1] = 0x81;
+  SPRITE_POINTERS[2] = 0x82;
   POKE(VIC_SPR_COL(0), 0x01);  /* white */
   POKE(VIC_SPR_COL(1), 0x01);
   POKE(VIC_SPR_COL(2), 0x07);  /* yellow ball */

package/examples/gb/main.asm

@@ -4,7 +4,7 @@
 ; it to the BG map, enables the LCD, then loops reading joypad and
 ; scrolling the BG. Build with:
 ;
-;   buildSource({platform:"gb", source: <this>})
+;   build({ output: "rom", platform:"gb", source: <this>})
 ;
 ; rgbfix gets applied automatically by buildForPlatform so the header
 ; checksum is valid.

package/examples/gb/main.c

@@ -1,7 +1,7 @@
 /* ── Hello, Game Boy in C — SDCC sm83 port ─────────────────────────
  * Minimal: cycle the BG palette on every vblank.
  *
- * Build: buildSource({ platform: "gb", source: <this file>, language: "c" })
+ * Build: build({ output: "rom",  platform: "gb", source: <this file>, language: "c" })
  *
  * SDCC 4.4.0 codegen quirks to avoid in `__sfr __at` register-heavy
  * code:

package/examples/gb/templates/puzzle.c

@@ -118,7 +118,7 @@ static void lock_piece(void) {
                 grid[r][c]     = 0;
                 grid[r][c + 1] = 0;
                 grid[r][c + 2] = 0;
-                if (score < 65500) score += 30;
+                if (score < 65500u) score += 30;
             }
         }
     }

package/examples/gb/templates/racing.c

@@ -153,6 +153,6 @@ void main(void) {
         break;
       }
     }
-    if (score < 65500) score++;
+    if (score < 65500u) score++;
   }
 }

package/examples/gb/templates/shmup.c

@@ -162,7 +162,7 @@ void main(void) {
                 if (aabb(&bullets[i], &enemies[j])) {
                     bullets[i].alive = 0;
                     enemies[j].alive = 0;
-                    if (score < 65500) score += 10;
+                    if (score < 65500u) score += 10;
                     sound_play_noise(6);
                     break;
                 }

package/examples/gba/templates/gba_hello.c

@@ -5,7 +5,7 @@
  * pixel that moves left/right via the d-pad.
  *
  * Build via romdev:
- *   buildSource({platform:"gba", language:"c", runtime:"libgba",
+ *   build({ output: "rom", platform:"gba", language:"c", runtime:"libgba",
  *                source: <this file>})
  *
  * NOTE: the DEFAULT GBA runtime is libtonc (use `tonc_hello.c` instead

package/examples/gba/templates/maxmod_demo.c

@@ -10,7 +10,7 @@
  *   4. mmStart(MOD_<NAME>_FROM_HEADER, mode) to begin playback.
  *
  * Build via romdev:
- *   buildSource({
+ *   build({ output: "rom", 
  *     platform: "gba",
  *     language: "c",
  *     source:   <this file>,

package/examples/gba/templates/puzzle.c

@@ -22,6 +22,20 @@
 #include <tonc.h>
 #include "gba_sfx.h"
 
+/* draw a 5-digit score WITHOUT tte_printf (broken in this libtonc — GBA-1). */
+static void draw_score(int x, unsigned v) {
+    char buf[24];
+    int i, n = 0;
+    buf[n++]='#'; buf[n++]='{'; buf[n++]='P'; buf[n++]=':';
+    if (x >= 100) buf[n++] = '0' + (x/100)%10;
+    if (x >= 10)  buf[n++] = '0' + (x/10)%10;
+    buf[n++] = '0' + x%10;
+    buf[n++]=','; buf[n++]='8'; buf[n++]='}';
+    for (i = 4; i >= 0; i--) { buf[n+i] = '0' + (v % 10); v /= 10; }
+    n += 5; buf[n] = 0;
+    tte_write(buf);
+}
+
 #define COLS 6
 #define ROWS 12
 
@@ -134,7 +148,7 @@ static void lock_piece(void) {
                 grid[r][c]     = 0;
                 grid[r][c + 1] = 0;
                 grid[r][c + 2] = 0;
-                if (score < 65500) score += 30;
+                if (score < 65500u) score += 30;
                 sfx_tone(1, 1700, 10);  /* triple-clear chime */
             }
         }
@@ -211,7 +225,7 @@ int main(void) {
             new_piece();
             prev = now;
             tte_erase_rect(88 + 6*8, 8, 88 + 11*8, 16);
-            tte_printf("#{P:%d,8}%05d", 88 + 6*8, score);
+            draw_score(88 + 6*8, score);
             continue;
         }
         prev = now;
@@ -231,7 +245,7 @@ int main(void) {
         draw_piece(piece_x, piece_y, 0);
 
         tte_erase_rect(88 + 6*8, 8, 88 + 11*8, 16);
-        tte_printf("#{P:%d,8}%05d", 88 + 6*8, score);
+        draw_score(88 + 6*8, score);
     }
     return 0;
 }