romdevtools 0.26.0 → 0.28.0

package/src/mcp/tools/project.js

@@ -92,7 +92,7 @@ const TEMPLATES = {
       linkerConfig: { presetSrc: "presets/nes/chr-ram-runtime.cfg", dst: "chr-ram-runtime.cfg" },
       lang: "C (cc65)",
       ext: ".nes",
-      describe: "Match-3 falling-block puzzle. 6×12 grid, 1×3 active piece (3 colors), rotate via A, soft-drop on DOWN, horizontal-triple clear.",
+      describe: "Match-3 falling-block puzzle. 6×12 grid, 1×3 active piece (3 colors), rotate via A, soft-drop on DOWN, 3+-in-a-row clears in all 4 directions (H/V/diagonals) with gravity + cascade chains.",
     },
     sports: {
       main: "templates/sports.c",
@@ -214,7 +214,7 @@ const TEMPLATES = {
       ],
       lang: "C (SDCC sm83)",
       ext: ".gb",
-      describe: "Match-3 falling-block puzzle scaffold for GB. 6×12 grid rendered via BG tilemap, 1×3 active piece (3 colours via 3 BG tile shapes), rotate via A, hard-drop on START, horizontal-triple clear.",
+      describe: "Match-3 falling-block puzzle scaffold for GB. 6×12 grid rendered via BG tilemap, 1×3 active piece (3 colours via 3 BG tile shapes), rotate via A, hard-drop on START, 3+-in-a-row clears in all 4 directions (H/V/diagonals) with gravity + cascade chains.",
     },
     sports: {
       main: "templates/sports.c",
@@ -284,7 +284,7 @@ const TEMPLATES = {
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches a falling object with the d-pad; full game loop with waitvsync(), two sprites, collision, scoring."),
       shmup: mk("shmup", "Vertical shoot-'em-up for PC Engine. Player ship + bullet/enemy object pools, a wave spawner, AABB collisions, score HUD, scrolling-band starfield BG. d-pad flies, button I fires. The base for any action shooter."),
       platformer: mk("platformer", "Side-scrolling platformer for PC Engine. Gravity + jump + land-on-top platform collision, a multi-screen world streamed via BG X-scroll (BXR), solid platform tiles, sub-pixel physics. d-pad moves, button I jumps."),
-      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for PC Engine. A 6x12 well drawn with BG tiles, a 1x3 active piece you move/rotate/soft-drop/hard-drop, horizontal-triple clears, score. d-pad moves, I rotates, II hard-drops."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for PC Engine. A 6x12 well drawn with BG tiles, a 1x3 active piece you move/rotate/soft-drop/hard-drop, 3+-in-a-row clears (H+V) with gravity + cascade chains, score. d-pad moves, I rotates, II hard-drops."),
       sports: mk("sports", "Pong-style sports game for PC Engine. Two paddles + a bouncing ball on a netted court, score to 9, paddle-deflect physics; player 2 falls back to chase-AI when no input. d-pad moves P1."),
       racing: mk("racing", "Top-down lane racer for PC Engine. Player car at the bottom, obstacle cars spawn from the top and slide down, LEFT/RIGHT switches lanes, speed grows with score, crash freeze + auto-reset. Scrolling road BG."),
     };
@@ -305,7 +305,7 @@ const TEMPLATES = {
       catch_game: mk("catch_game", "A complete tiny game: a paddle catches falling fruit with the joystick; full game loop with vblank sync, two sprites, collision, scoring."),
       shmup: mk("shmup", "Vertical-shmup scaffold for MSX (screen 2). Player ship (sprite plane 0) + 4 bullet + 4 enemy object pools, a wave spawner, AABB collision, on-screen SCORE tiles, over a banded starfield filling the whole 32x24 name table. Joystick PORT 1 moves the ship (UP/DOWN/LEFT/RIGHT), trigger A (GTTRIG) fires; PSG blip on fire, noise-ish tone on a kill. Interrupt-free vsync via VDP status S#0. Extend with enemy fire, lives, scrolling stars."),
       platformer: mk("platformer", "Side-scrolling platformer for MSX (screen 2). Subpixel gravity/jump/land-on-top collision against a table of platforms across a 512-px (64-cell) world, drawn by COLUMN STREAMING into the wrapping screen-2 name table as the camera follows the player; the player sprite draws in screen space. Joystick LEFT/RIGHT walks, trigger A jumps (only when grounded); PSG jump blip. Interrupt-free vsync. Extend with enemies, pickups, goal."),
-      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for MSX (screen 2). A 6-wide x 12-tall well drawn with the BG tilemap (distinct R/G/B cell tiles + grey border + dim field interior so the playfield is always visible). A 1x3 active piece: joystick LEFT/RIGHT shifts, trigger A rotates the colour order, DOWN soft-drops, trigger B hard-drops; horizontal-triple clears score with a PSG chime. Interrupt-free vsync. Extend with vertical/diagonal matches, gravity-collapse, levels."),
+      puzzle: mk("puzzle", "Match-3 / falling-block puzzle for MSX (screen 2). A 6-wide x 12-tall well drawn with the BG tilemap (distinct R/G/B cell tiles + grey border + dim field interior so the playfield is always visible). A 1x3 active piece: joystick LEFT/RIGHT shifts, trigger A rotates the colour order, DOWN soft-drops, trigger B hard-drops; 3+-in-a-row clears in all 4 directions with gravity + cascade chains; PSG chime per clear. Interrupt-free vsync. Extend with levels/next-piece preview."),
       sports: mk("sports", "Pong-style 2-player sports for MSX (screen 2). Court (green field + white sidelines + dashed centre net) fills the 32x24 name table; two paddles (stacked sprites) + a ball. Player 1 = joystick PORT 1 UP/DOWN; Player 2 = joystick PORT 2 UP/DOWN, falling back to chase-the-ball AI when no second pad is present so it is playable solo. Wall/paddle bounces + scoring with PSG bonks. Interrupt-free vsync. Extend with serve angles, score display, win condition."),
       racing: mk("racing", "Top-down 3-lane racing for MSX (screen 2). Grey road + green-grass shoulders fill the name table; player car at the bottom, obstacle cars (object pool) spawn at the top and slide down. Joystick LEFT/RIGHT (edge-detected) switches lanes; obstacle speed grows with score; an AABB crash triggers a ~60-frame freeze then auto-reset, with a PSG crash tone. SCORE drawn as tiles. Interrupt-free vsync. Extend with pseudo-3D road, fuel, multiple cars."),
     };
@@ -351,9 +351,19 @@ TEMPLATES.gbc = {
     describe: "SIDE-SCROLLING platformer for GBC. Full CGB color palette (BG + sprite via BCPS/OCPS) over the GB side-scroller core: subpixel gravity + jump + land-on-top collision against platforms across a 256-px world (the wrapping BG map). The camera follows the player and scrolls the BG via SCX; the player sprite draws in screen space. A=jump, d-pad=move. One BG map wide (no streaming) — for a wider world, stream a new BG-map column on each 8px camera step (window for a fixed HUD). See the GBC MENTAL_MODEL.md 'Horizontal scrolling'. Extend with enemies, goals, pickups.",
   },
   puzzle: {
-    main: "templates/puzzle.c", runtime: GBC_RUNTIME,
+    main: "templates/puzzle.c",
+    runtime: [
+      ...GBC_RUNTIME,
+      { src: "lib/c/font.h", dst: "font.h" },  /* digits+A-Z 2bpp glyphs for the HUD */
+    ],
     lang: GBC_LANG, ext: ".gbc",
-    describe: "Match-3 puzzle for GBC. Three colored cells (BG palette via BCPS/BCPD), rotate + soft-drop + hard-drop + triple-clear chime.",
+    describe: "Falling-jewel matcher for GBC (the polished reference puzzle). 8x17 well, 6 jewel colors with " +
+      "real CGB palettes, matches in all 4 directions (H/V/both diagonals), gravity + cascade chains, magic " +
+      "jewel every 18th piece, level speedup, 6-digit score, title + game-over screens, SFX + toggleable " +
+      "music. Rendering: falling column + NEXT preview are OAM sprites; the locked well is BG tiles via a " +
+      "COLLECT/FLUSH vblank queue with an idle scrub (writes outside vblank silently drop on this core — " +
+      "never bypass the queue). Statics need dataLoc 0xC200 (above shadow_oam at $C100) — the project build " +
+      "recipe sets that automatically.",
   },
   sports: {
     main: "templates/sports.c", runtime: GBC_RUNTIME,
@@ -398,6 +408,11 @@ TEMPLATES.gbc = {
 // against. Factored to a constant so adding a new template is a one-line
 // change at the bottom.
 const SMS_RUNTIME = [
+  // The crt0 ships IN the project (like GG/MSX) so the dir is genuinely
+  // self-contained: build({output:'project'}) routes it via the crt0 channel
+  // (projectBuildRecipe), and an external stock-SDCC rebuild has the real
+  // boot stub on disk instead of silently linking SDCC's non-booting one.
+  { src: "lib/c/sms_crt0.s",      dst: "sms_crt0.s" },
   { src: "lib/c/sms_hw.h",        dst: "sms_hw.h" },
   { src: "lib/c/vdp_init.c",      dst: "vdp_init.c" },
   { src: "lib/c/load_palette.c",  dst: "load_palette.c" },
@@ -764,7 +779,7 @@ TEMPLATES.snes = {
     runtimeDirs: SNES_PVSNESLIB_VENDOR_DIRS,
     lang: "C (tcc-65816 + PVSnesLib)",
     ext: ".sfc",
-    describe: "Match-3 falling-block puzzle for SNES. 6×12 grid (text mode), rotate/soft-drop/hard-drop, horizontal-triple clear. Rotate click + clear chime via bundled SPC700 sfx.",
+    describe: "Match-3 falling-block puzzle for SNES. 6×12 grid (text mode), rotate/soft-drop/hard-drop, 3+-in-a-row clears in all 4 directions with gravity + cascade chains. Rotate click + clear chime via bundled SPC700 sfx.",
   },
   sports: {
     main: "templates/sports.c",
@@ -939,7 +954,7 @@ TEMPLATES.genesis = {
     runtimeDirs: SGDK_RUNTIME_DIRS,
     lang: SGDK_LANG,
     ext: ".bin",
-    describe: "Match-3 falling-block puzzle genre scaffold. 6×12 grid, 1×3 active piece (3 colours), rotate via A, soft-drop on DOWN, hard-drop on START, horizontal-triple clear. xorshift RNG so cell colours actually vary.",
+    describe: "Match-3 falling-block puzzle genre scaffold. 6×12 grid, 1×3 active piece (3 colours), rotate via A, soft-drop on DOWN, hard-drop on START, 3+-in-a-row clears in all 4 directions with gravity + cascade chains. xorshift RNG so cell colours actually vary.",
   },
   sports: {
     main: "templates/sports.c",
@@ -1757,7 +1772,18 @@ Compiles **C89**, not C99/C11. Stick to:
   let filesSection = `## Files\n\n- \`${mainFilename}\` — your game's entry point.\n`;
   if (tmpl?.runtime) {
     for (const { dst } of tmpl.runtime) {
-      filesSection += `- \`${dst}\` — runtime helper. **You own this** — edit or replace at will.\n`;
+      if (dst === "patch-header.js") {
+        // NOT game code — calling it a "runtime helper" implied it compiles
+        // into the ROM and confused readers. It's a standalone sidecar tool.
+        filesSection += `- \`${dst}\` — sidecar TOOL, not game code (never compiled into the ROM). ` +
+          `Stamps the Nintendo logo + header/global checksums a GB ROM needs to boot ` +
+          `(\`node patch-header.js game.gb\`) — a zero-install stand-in for RGBDS's rgbfix when you ` +
+          `rebuild OUTSIDE romdev with stock SDCC. romdev's own builds fix the header automatically.\n`;
+      } else if (dst.endsWith("_crt0.s")) {
+        filesSection += `- \`${dst}\` — startup assembly (reset/interrupt vectors, RAM init; routed as the crt0 by the project build). **You own this.**\n`;
+      } else {
+        filesSection += `- \`${dst}\` — runtime helper. **You own this** — edit or replace at will.\n`;
+      }
     }
   }
   if (tmpl?.crt0) {

package/src/mcp/tools/toolchain.js

@@ -266,7 +266,7 @@ export function installToolchainCore({ id }) {
 }
 
 export function registerToolchainTools(server, z, sessionKey) {
-  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, inesHeader, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
+  async function buildSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, crt0, crt0Path, codeLoc, dataLoc, options, linkerConfig, linkerConfigPath, inesHeader, outputPath, inline = false, includeSymbols = false, lint = "advisory", runtime, maxmod, rebuildSdk }) {
       // Reject conflicting inline vs path args — fail loud, not silent.
       if (source != null && sourcePath != null) {
         throw new Error("build({output:'rom'}): pass either `source` OR `sourcePath`, not both.");
@@ -281,6 +281,12 @@ export function registerToolchainTools(server, z, sessionKey) {
       if (crt0Path) {
         crt0 = await readFile(crt0Path, "utf-8");
       }
+      // linkerConfigPath: read the .cfg from disk so a large multi-bank
+      // config (e.g. a disasm'd mapper-2 rebuild) isn't re-streamed through
+      // context on every build (0.27.0 feedback #2).
+      if (linkerConfigPath && linkerConfig == null) {
+        linkerConfig = await readFile(linkerConfigPath, "utf-8");
+      }
       // Auto-inject the bundled crt0 for SMS/GG when caller didn't pass
       // one. Stock SDCC crt0 doesn't boot these targets; without this,
       // user main() is never called → black screen. See AUTO_CRT0_PLATFORMS.
@@ -464,7 +470,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       return jsonContent(payload);
   }
 
-  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, inesHeader, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
+  async function runSourceImpl({ platform, language, source, sourcePath, sources, sourcesPaths, includes, binaryIncludes, binaryIncludePaths, includePaths, runtime, maxmod, rebuildSdk, crt0, crt0Path, codeLoc, dataLoc, linkerConfig, linkerConfigPath, inesHeader, path: projPath, frames = 60, holdInputs, screenshotPath, projectName }) {
       const { buildForPlatform } = await import("../../toolchains/index.js");
       const resolved = resolveCore(platform);
       if (!resolved) throw new Error(`no core available for platform '${platform}'`);
@@ -480,6 +486,7 @@ export function registerToolchainTools(server, z, sessionKey) {
         binaryIncludes = { ...(binaryIncludes ?? {}), ...r.binaryIncludes };
         if (r.crt0 != null) crt0 = r.crt0;
         if (r.codeLoc != null) codeLoc = r.codeLoc;
+        if (r.dataLoc != null && dataLoc == null) dataLoc = r.dataLoc;
         if (r.linkerConfig != null && linkerConfig == null) linkerConfig = r.linkerConfig;
         if (r.runtime != null && runtime == null) runtime = r.runtime;
         if (r.maxmod != null && maxmod == null) maxmod = r.maxmod;
@@ -510,6 +517,9 @@ export function registerToolchainTools(server, z, sessionKey) {
       if (crt0Path) {
         crt0 = await readFile(crt0Path, "utf-8");
       }
+      if (linkerConfigPath && linkerConfig == null) {
+        linkerConfig = await readFile(linkerConfigPath, "utf-8");
+      }
       // Auto-inject bundled crt0 for SMS/GG when caller didn't pass one
       // (stock SDCC crt0 doesn't boot these targets — see buildSource).
       if (crt0 == null) {
@@ -714,6 +724,7 @@ export function registerToolchainTools(server, z, sessionKey) {
       dataLoc: z.coerce.number().int().optional().describe("SDCC — _DATA (WRAM) load address (default $C000 on Z80). NOT read by output:'romWithDebug'."),
       options: z.array(z.string()).optional().describe("output:'rom' — extra toolchain CLI options."),
       linkerConfig: z.string().optional().describe("ld65 linker config (cc65). NES presets: 'chr-ram-runtime' (RECOMMENDED for homebrew C — full crt0 + iNES header + NMI w/ OAM DMA + `_shadow_oam` at $0200), 'chr-ram' (bare nmi:rti stub), 'chr-rom' (cc65-C with FIXED CHR-ROM art — segment split + CHARS segment; supply CHR via binaryIncludePaths into a CHARS source + the header via `inesHeader`). Or full .cfg contents. Preset NAMES only resolve on output:'rom'/'run'; output:'romWithDebug' takes raw .cfg contents only. **For rebuilding a commercial NROM game from its disassembly, prefer `inesHeader` over a raw .cfg.**"),
+      linkerConfigPath: z.string().optional().describe("Path-based `linkerConfig`: absolute path to a .cfg file on disk (the server reads it — the cfg never enters your context; e.g. the multi-bank cfg a banked-NES disasm project ships). Ignored when `linkerConfig` is passed inline."),
       inesHeader: z.object({
         prgBanks: z.coerce.number().int().min(1).max(255).describe("16KB PRG-ROM banks (1 = NROM-128, 2 = NROM-256)."),
         chrBanks: z.coerce.number().int().min(0).max(255).optional().describe("8KB CHR-ROM banks (0 = CHR-RAM, no CHARS segment). Default 0."),
@@ -785,8 +796,8 @@ export function registerToolchainTools(server, z, sessionKey) {
  */
 export function projectBuildRecipe(platform, names) {
   const has = (n) => names.includes(n);
-  /** @type {{crt0File:string|null, codeLoc:number|undefined, linkerConfig:string|undefined, runtime:string|undefined, maxmod:boolean|undefined, skip:Set<string>, includeAsC:Set<string>}} */
-  const r = { crt0File: null, codeLoc: undefined, linkerConfig: undefined, runtime: undefined, maxmod: undefined, skip: new Set(), includeAsC: new Set() };
+  /** @type {{crt0File:string|null, codeLoc:number|undefined, dataLoc:number|undefined, linkerConfig:string|undefined, runtime:string|undefined, maxmod:boolean|undefined, skip:Set<string>, includeAsC:Set<string>}} */
+  const r = { crt0File: null, codeLoc: undefined, dataLoc: undefined, linkerConfig: undefined, runtime: undefined, maxmod: undefined, skip: new Set(), includeAsC: new Set() };
 
   // Reference/upstream sources ship for grepping, not compiling (e.g. GB
   // music_demo's hUGEDriver.upstream.asm — the .c port is what builds). Skip
@@ -796,7 +807,11 @@ export function projectBuildRecipe(platform, names) {
   if (platform === "gb" || platform === "gbc") {
     // GB/GBC ship gb_crt0.s — it MUST go via crt0+codeLoc:0x150, never as a
     // source (SDCC emits its own gsinit → "Multiple definition of gsinit").
-    if (has("gb_crt0.s")) { r.crt0File = "gb_crt0.s"; r.codeLoc = 0x150; }
+    // dataLoc 0xC200: statics start ABOVE shadow_oam ($C100-$C19F, fixed by
+    // the runtime). The sdld default of $C000 let any project with >256 bytes
+    // of statics silently overlap the OAM shadow — oam_clear() then zeroed
+    // game state (grid/RNG seed). 512 bytes of 8KB WRAM is cheap insurance.
+    if (has("gb_crt0.s")) { r.crt0File = "gb_crt0.s"; r.codeLoc = 0x150; r.dataLoc = 0xC200; }
   } else if (platform === "nes") {
     // A SCAFFOLDED NES project ships nes_runtime.c + a crt0 + a .cfg and needs
     // the chr-ram-runtime preset (it defines the OAM/CHARS segments + a NMI with
@@ -824,9 +839,17 @@ export function projectBuildRecipe(platform, names) {
     // msx_crt0.s through crt0 makes ITS header + init the cartridge entry.
     if (has("msx_crt0.s")) { r.crt0File = "msx_crt0.s"; r.codeLoc = 0x4010; }
   } else if (platform === "sms" || platform === "gg") {
-    // SMS/GG auto-inject their bundled crt0 inside buildForPlatform — so the
-    // scaffold's own *_crt0.s would be a DUPLICATE. Skip it.
-    for (const n of names) if (/_crt0\.s$/i.test(n)) r.skip.add(n);
+    // SMS/GG: route the project's *_crt0.s through the crt0 channel (like
+    // GB/MSX), NOT as a plain source TU. The OLD recipe skipped it on the
+    // belief that "buildForPlatform auto-injects the bundled crt0" — IT DOES
+    // NOT (only the output:'rom'/'run' MCP handlers auto-inject). So every
+    // output:'project' SMS/GG build linked SDCC's STOCK z80 crt0, whose boot
+    // is `ld a,#2 / rst $08 / halt` — main() never ran and every scaffold
+    // booted to a BLACK SCREEN (the RetroDECK "all broken" report; our
+    // output:'run' verifications were false-green via the other path).
+    // readProjectDir falls back to the bundled crt0 when the dir has none.
+    const crt0Name = names.find((n) => /_crt0\.s$/i.test(n));
+    if (crt0Name) r.crt0File = crt0Name;
   } else if (platform === "genesis" || platform === "megadrive" || platform === "md") {
     // SGDK supplies sega startup + rom header. The scaffold dir may contain
     // generated intermediates (sega.s, sega.preprocessed.s, rom_header.*, and an
@@ -919,6 +942,15 @@ export async function readProjectDir(projPath, platform) {
     }
   }
 
+  // SMS/GG with no crt0 file in the dir → fall back to the bundled crt0,
+  // exactly like the output:'rom'/'run' handlers do. Without this the link
+  // silently uses SDCC's stock z80 crt0, which never calls main() (black
+  // screen at boot). The SMS scaffold historically shipped without a crt0
+  // file, so this fallback is load-bearing for existing project dirs.
+  if (crt0 == null && (platform === "sms" || platform === "gg")) {
+    crt0 = await resolveAutoCrt0(platform);
+  }
+
   // GBA runtime refinement: libgba if the entry includes <gba.h>, else the
   // libtonc default the recipe set.
   let runtime = recipe.runtime;
@@ -926,11 +958,11 @@ export async function readProjectDir(projPath, platform) {
     runtime = "libgba";
   }
 
-  return { sources, includes, binaryIncludes, crt0, codeLoc: recipe.codeLoc, linkerConfig: recipe.linkerConfig, runtime, maxmod: recipe.maxmod };
+  return { sources, includes, binaryIncludes, crt0, codeLoc: recipe.codeLoc, dataLoc: recipe.dataLoc, linkerConfig: recipe.linkerConfig, runtime, maxmod: recipe.maxmod };
 }
 
 export async function buildProjectCore({ path: projPath, platform, outputPath }) {
-  const { sources, includes, binaryIncludes, crt0, codeLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
+  const { sources, includes, binaryIncludes, crt0, codeLoc, dataLoc, linkerConfig, runtime, maxmod } = await readProjectDir(projPath, platform);
 
   // Linker preset: the recipe names it (e.g. NES 'chr-ram-runtime', which ships
   // the OAM/CHARS segments + its own crt0). resolveLinkerConfig also returns any
@@ -968,6 +1000,7 @@ export async function buildProjectCore({ path: projPath, platform, outputPath })
     linkerConfig: resolvedLinkerConfig,
     crt0: crt0Rel,
     codeLoc,
+    dataLoc,
   });
   if (outputPath && result.binary) {
     await mkdir(path.dirname(outputPath), { recursive: true });