romdevtools 0.22.1 → 0.24.0

package/CHANGELOG.md

@@ -4,6 +4,109 @@ 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.24.0
+
+### Added — C64 keyboard + joyport input (VICE core patch)
+An agent RE'ing C64 Uridium could reach the intro via joystick but couldn't ENTER
+gameplay — the game needs **F1** (1 player) + fire on **port 2**, and romdev's
+input was joypad-mask-only. Many C64 games gate gameplay behind KEYBOARD setup
+screens that joystick can't reach. The VICE core now exports
+`romdev_key_matrix`/`romdev_kbdbuf_feed`/`romdev_joyport_*`, surfaced as:
+- **`input({op:'pressKey', key})`** — press a C64 keyboard key (F1/F3/F5/F7,
+  Return, Space, Run/Stop, a–z, 0–9, …) by driving the C64 8×8 key matrix.
+- **`input({op:'typeText', text})`** — feed a string into the kernal keyboard
+  buffer (LOAD/RUN/filenames); `\r` → RETURN.
+- **`input({op:'joyport', joyport?})`** — read/set the active C64 joystick port
+  (1 or 2; default 2, most games).
+- `input({op:'layout', platform:'c64'})` now reports the keyboard keys + joyport.
+
+**A controller alone plays C64** (the Batocera/RetroDeck model — no physical
+keyboard needed). Spare pad buttons/stick map to the C64 keyboard keys games need
+to start: X/Space=Space, L2=Run/Stop, R2=Return, top face / right-stick =
+F1/F3/F5/F7; d-pad + Fire stay the joystick. Unified in the host so it works the
+same in the playtest window AND for the agent's headless `setInput`. No-controller
+keyboard fallback maps PC F1–F4/Space/Enter to the same C64 keys.
+`playtest({op:'open'})` on a C64 game relays the controls. (romdev-core-vice 0.7.0.)
+
+### Changed — leaner, less-confusing agent docs (AGENTS.md / SKILL.md)
+AGENTS.md was loaded in full every session for every platform — ~30k tokens, of
+which ~13k was platform-specific or duplicated detail an agent on one platform
+never needed (and could misapply across platforms). Cut **~31% (~9.5k tokens)**:
+- Per-platform debug-tooling detail → each platform's `MENTAL_MODEL.md`.
+- The ROM-hacking workflow → folded into the `ROMHACKING_PLAYBOOK.md` guide.
+- Toolchain landmines → per-platform `TROUBLESHOOTING.md`/`SDCC_GOTCHAS.md`.
+- Disassembler flag reference → it's already in the disasm tool's own schema.
+All reachable on demand via `platform({op:'doc'})`; AGENTS.md keeps generic
+guidance + symptom→doc pointers. **"Read your target platform's
+`platform({op:'doc', name:'mental_model'})` BEFORE you write code for it"** is now
+a top-level rule (the footguns live there) — so the on-demand docs actually get
+read. The dynamic SKILL.md inherits all of this.
+
+## 0.23.0
+
+Response to real build-session feedback. Theme: bugs found, false alarms
+removed, and — the recurring finding — **tools that already existed but agents
+couldn't find them**.
+
+### Fixed — multi-tenant host cross-talk (a whole class of bugs)
+`sprites({op:'inspect', platform:'genesis'})` returned a *GBC*-flavored error while
+Genesis was loaded. Root cause: `inspectSpritesCore` / `getCPUStateCore` /
+`getAudioStateCore` / `inspectBackgroundMapCore` / `inspectPatternTilesCore` were
+module-global `export let` bindings reassigned per session, each closing over THAT
+registration's `sessionKey` — so the last session to register stole the host for
+everyone. Now the caller's `sessionKey` is threaded through. Verified on all 7
+tile-based sprite platforms with sessions live simultaneously.
+
+### Fixed — SMS/GG C crt0: `static x = N;` initializers booted to 0
+Investigating two reported "silent sm83 miscompiles" (32-bit xorshift, indexed
+loop): NEITHER reproduces on GB/GBC — both produce byte-exact output. The real bug
+was a genuine **z80 crt0 defect**: `sms_crt0.s`/`gg_crt0.s` placed `_INITIALIZER`
+in RAM not ROM, so the gsinit `ldir` copied RAM onto itself → every value-static
+booted 0 and BSS wasn't zeroed. Fixed both (mirrors the correct `gb_crt0.s`).
+Re-verified all SMS/GG scaffolds still build clean + render.
+
+### Changed — lint stops crying wolf on WRAM copies
+The SDCC `xdata-copy-miscompile` warning fired on EVERY `dst[i]=src[i]` loop,
+including plain WRAM arrays (the message even said "ignore if plain WRAM") —
+training agents to ignore lint. Now: provably-VRAM dest → warning, plain RAM array
+→ suppressed, unknown → info. (Deliberately did NOT add the requested 32-bit-shift
+/ short-loop lint heuristics — they'd be false positives for non-bugs.)
+
+### Added — feedback ergonomics
+- **`frame({op:'screenshot', scale})` up-scales** (integer ≥2, nearest-neighbor)
+  for legible handheld shots (GB 160×144 → 640×576 at `scale:4`), plus the
+  existing `0<scale<1` downscale. All platforms.
+- **Cheap symbol→address:** `symbols({op:'resolve', dbgPath|mapPath, name})` reads
+  the map FILE on disk (no 63 KB round-trip through context); `build({output:
+  'romWithDebug', resolveSymbols:[...]})` folds just those addresses into the
+  result. cc65 `.dbg` / sdld `.map` / GNU ld `.map`.
+
+### Added — Genesis feel/perf diagnostics
+- **`watch({on:'dma', perFrame:true})`** — per-frame DMA-bytes timeline + spike
+  detection (catches "rewriting tilemaps in the frame loop", the #1 Genesis feel
+  bug). A hardware-scroll scaffold settles to a flat ~8 bytes/frame.
+- **`scaffold` template `two_plane_parallax`** — plane-A foreground + plane-B
+  repeated starfield + player sprite, hardware scroll only, zero loop-time tilemap
+  writes. Builds clean, renders, scrolls (verified).
+- Genesis MENTAL_MODEL/TROUBLESHOOTING: "do NOT rewrite tilemaps in the frame
+  loop", logical-vs-hardware plane size, the correct parallax loop, Sonic-style
+  column streaming, and a "why does movement feel choppy?" recipe.
+
+### Changed — discoverability (the recurring root cause)
+Several feedback "feature asks" were tools that already existed. `recordSession`
+(motion/telemetry timeline) was mislabeled in the catalog as "capture inputs for
+replay"; relabeled. New AGENTS.md "Diagnosing behavior over time (game-feel)"
+section maps symptom → existing tool (choppy movement → `recordSession`/`watch`
+series on scroll+sprite; wrong-but-clean value → `resolveSymbols` + `memory` read;
+can't-read-the-BG → `background({view:'map'})` + `screenshot scale:4`).
+
+### Other
+- `build({output:'project', path})` already defaults the gb/gbc/sms/gg/msx crt0 +
+  codeLoc — documented (the GBC agent was hand-passing them to `output:'rom'`).
+- P4 doc + a new info-level `wram-static-overlap` lint advisory (hardcoded
+  `$C000–$C0FF` pointer overlapping SDCC's static-data segment — the actual cause
+  of the reporter's "monochrome RNG").
+
 ## 0.22.1
 
 Doc-only follow-up to 0.22.0's movement-analysis feedback: the `pressDuring`

package/examples/genesis/templates/platformer.c

@@ -13,7 +13,11 @@
  * level fits in the scroll plane and plain VDP_setHorizontalScroll moves
  * it — a real working scroller with no streaming. For a world WIDER than
  * 512 px you additionally stream the column entering view each time camX
- * crosses an 8-px boundary (see MENTAL_MODEL.md "Horizontal scrolling").
+ * crosses an 8-px boundary (see MENTAL_MODEL.md "How Sonic-style large
+ * maps REALLY work"). For a from-scratch smooth-scroll + parallax
+ * starting point with NO per-frame tilemap writes, see the
+ * two_plane_parallax template + MENTAL_MODEL.md "Scrolling, parallax &
+ * the feel trap".
  */
 
 #include <genesis.h>

package/examples/genesis/templates/two_plane_parallax.c

@@ -0,0 +1,166 @@
+/* ── two_plane_parallax.c — Genesis SGDK two-plane parallax scaffold ──
+ *
+ * The "Uridium / Sonic-feel" starting point: a side-scrolling world that
+ * moves SMOOTHLY because the frame loop does HARDWARE SCROLL ONLY. There
+ * are ZERO tilemap writes inside the loop — the two planes are painted
+ * ONCE at setup, and every frame we just nudge two scroll registers and
+ * re-stage one sprite. This is the single most important thing to copy:
+ *
+ *     ★ Do NOT rewrite tilemaps in the frame loop. ★
+ *
+ * Rewriting a plane each frame is a big VDP/DMA burst that overruns
+ * vblank and makes movement feel choppy/juddery. Hardware scroll is free.
+ *
+ * Layout:
+ *   - Plane A (foreground): a painted "world" — a ground strip + scattered
+ *     platform blocks across a 512-px (64-cell) plane. Scrolls 1:1 with
+ *     the camera.
+ *   - Plane B (background): a repeated starfield filling the whole plane.
+ *     Scrolls at 1/4 the camera speed for parallax depth (far things
+ *     move slower). Because Plane B is filled edge-to-edge and the VDP
+ *     scroll wraps within the plane, it tiles forever with no redraw.
+ *   - One hardware sprite = the player, drawn in SCREEN space.
+ *
+ * Drive it: D-pad LEFT/RIGHT scrolls the camera (the player walks within
+ * the world). The camera clamps to the world edges.
+ *
+ * IMPORTANT (logical vs hardware plane size): the Genesis has ONE shared
+ * plane-size setting for BOTH planes. We use the default 64x32 cells
+ * (512x256 px). A "32-wide level" still lives inside a 64-wide PHYSICAL
+ * plane — you don't get an independent per-plane size. See the Genesis
+ * MENTAL_MODEL.md "Scrolling, parallax & the feel trap".
+ *
+ * To go WIDER than 512 px (a true Sonic-size level) you keep this exact
+ * loop and add ONE thing: stream the single offscreen column that's about
+ * to scroll into view each time the camera crosses an 8-px tile boundary
+ * (a circular buffer in the 64-cell plane) — NOT a whole-plane redraw.
+ * See MENTAL_MODEL.md "How Sonic-style large maps really work".
+ */
+
+#include <genesis.h>
+
+/* ── Tiles (4bpp, 8 rows x 4 bytes). Indices live at/above TILE_USER_INDEX
+ *    so they don't clobber SGDK's font + system tiles below it. ── */
+#define T_BLANK   (TILE_USER_INDEX + 0)
+#define T_GROUND  (TILE_USER_INDEX + 1)
+#define T_BLOCK   (TILE_USER_INDEX + 2)
+#define T_PLAYER  (TILE_USER_INDEX + 3)
+#define T_STAR    (TILE_USER_INDEX + 4)
+
+static const u32 tile_blank[8]  = { 0,0,0,0,0,0,0,0 };
+/* Solid ground: lit top edge, darker body. */
+static const u32 tile_ground[8] = {
+    0x11111111, 0x12222221, 0x12222221, 0x12222221,
+    0x12222221, 0x12222221, 0x12222221, 0x12222221,
+};
+/* A floating platform block. */
+static const u32 tile_block[8]  = {
+    0x33333333, 0x34444443, 0x34444443, 0x34444443,
+    0x34444443, 0x34444443, 0x34444443, 0x33333333,
+};
+/* Player: a chunky diamond so it reads on screen. */
+static const u32 tile_player[8] = {
+    0x00055000, 0x00555500, 0x05555550, 0x55555555,
+    0x55555555, 0x05555550, 0x00555500, 0x00055000,
+};
+/* A single off-center star pixel on a dark field (background twinkle). */
+static const u32 tile_star[8]   = {
+    0x00000000, 0x00060000, 0x00000000, 0x00000600,
+    0x00000000, 0x06000000, 0x00000000, 0x00000060,
+};
+
+#define PLANE_W_CELLS 64          /* default plane is 64x32 cells       */
+#define WORLD_W       512         /* = 64 cells * 8 px (one plane wide)  */
+#define SCREEN_W      320         /* H40                                  */
+#define GROUND_Y      192         /* px — top of the ground strip         */
+
+/* Static foreground platforms in WORLD PIXEL coords. Painted ONCE. */
+typedef struct { s16 x, y, wcells; } Block;
+static const Block blocks[] = {
+    {  48, 152, 5 }, { 160, 128, 4 }, { 256, 160, 6 },
+    { 352, 112, 4 }, { 432, 144, 5 },
+};
+#define N_BLOCKS (sizeof(blocks) / sizeof(blocks[0]))
+
+/* Player WORLD x exposed for headless motion-trace inspection:
+ *   symbols({op:'resolve', name:'g_player_x'}) → read it over frames while
+ *   holding RIGHT and compare against the camera scroll (see MENTAL_MODEL
+ *   "Why does horizontal movement feel choppy?"). `volatile` keeps it from
+ *   being optimised into a register so the read resolves. */
+volatile s16 g_player_x = 32;     /* world px */
+volatile s16 g_cam_x    = 0;      /* camera scroll (world px) */
+
+int main(bool hard) {
+    (void)hard;
+
+    /* Palettes (BGR, 3 bits/chan). PAL0 = sprite, PAL1 = planes. */
+    PAL_setColor(0 +  5, 0x008E);  /* player orange (Uridium-ish) */
+    PAL_setColor(16 + 1, 0x0A86);  /* ground top   (light)  */
+    PAL_setColor(16 + 2, 0x0530);  /* ground body  (dark)   */
+    PAL_setColor(16 + 3, 0x0CCC);  /* block edge   (white)  */
+    PAL_setColor(16 + 4, 0x0844);  /* block body   (steel)  */
+    PAL_setColor(16 + 6, 0x0EEE);  /* star         (white)  */
+
+    /* Upload all tiles once. */
+    VDP_loadTileData(tile_blank,  T_BLANK,  1, DMA);
+    VDP_loadTileData(tile_ground, T_GROUND, 1, DMA);
+    VDP_loadTileData(tile_block,  T_BLOCK,  1, DMA);
+    VDP_loadTileData(tile_player, T_PLAYER, 1, DMA);
+    VDP_loadTileData(tile_star,   T_STAR,   1, DMA);
+
+    /* ── PAINT PLANE B (starfield) ONCE — fills the whole 64x32 plane so
+     *    it tiles forever as the scroll wraps. NEVER touched again. ── */
+    VDP_fillTileMapRect(BG_B, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_STAR),
+                        0, 0, PLANE_W_CELLS, 32);
+
+    /* ── PAINT PLANE A (foreground world) ONCE. ──
+     * Ground strip across the whole world width, then the platform blocks
+     * on top. After this, the loop does NOT write the tilemap again. */
+    VDP_fillTileMapRect(BG_A, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_GROUND),
+                        0, GROUND_Y >> 3, PLANE_W_CELLS, (256 - GROUND_Y) >> 3);
+    for (u16 i = 0; i < N_BLOCKS; i++) {
+        const Block* b = &blocks[i];
+        VDP_fillTileMapRect(BG_A, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_BLOCK),
+                            b->x >> 3, b->y >> 3, b->wcells, 1);
+    }
+
+    VDP_drawText("PARALLAX  D-PAD = SCROLL", 7, 1);
+
+    const s16 PLAYER_SPEED = 2;
+    s16 player_screen_x = SCREEN_W / 2 - 4;  /* player stays mid-screen */
+
+    while (TRUE) {
+        u16 pad = JOY_readJoypad(JOY_1);
+
+        /* Move the player through the WORLD. */
+        if (pad & BUTTON_LEFT)  g_player_x -= PLAYER_SPEED;
+        if (pad & BUTTON_RIGHT) g_player_x += PLAYER_SPEED;
+        if (g_player_x < 0)            g_player_x = 0;
+        if (g_player_x > WORLD_W - 8)  g_player_x = WORLD_W - 8;
+
+        /* Camera centers on the player, clamped to the world edges. */
+        s16 cam = g_player_x - (SCREEN_W / 2 - 4);
+        if (cam < 0)                    cam = 0;
+        if (cam > WORLD_W - SCREEN_W)   cam = WORLD_W - SCREEN_W;
+        g_cam_x = cam;
+
+        /* When the camera is hard against an edge, let the player walk to
+         * the screen edge instead of staying pinned to the centre. */
+        player_screen_x = g_player_x - cam;
+
+        /* ★ THE ENTIRE PER-FRAME RENDER COST: two scroll-register writes.
+         * Positive cam scrolls the plane LEFT, so we write the negative.
+         * Plane A: 1:1 with the world. Plane B: 1/4 speed = parallax. */
+        VDP_setHorizontalScroll(BG_A, -cam);
+        VDP_setHorizontalScroll(BG_B, -(cam >> 2));
+
+        /* Re-stage the one player sprite (screen space) + flush the SAT.
+         * SPRITE_SIZE(1,1) = 8x8. */
+        VDP_setSprite(0, player_screen_x, GROUND_Y - 8, SPRITE_SIZE(1, 1),
+                      TILE_ATTR_FULL(PAL0, 1, 0, 0, T_PLAYER));
+        VDP_updateSprites(1, DMA);
+
+        SYS_doVBlankProcess();
+    }
+    return 0;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "romdevtools",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "description": "Tool server giving coding agents full control of homebrew ROM development AND reverse-engineering/romhacking across 14 retro platforms (NES, SNES, GB, Genesis, Atari, C64, PC Engine, MSX, ...) 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",
@@ -57,7 +57,7 @@
     "romdev-core-gpgx": "0.10.0",
     "romdev-core-handy": "0.5.0",
     "romdev-core-prosystem": "0.6.0",
-    "romdev-core-vice": "0.6.0",
+    "romdev-core-vice": "0.7.0",
     "romdev-famitone": "0.1.0",
     "romdev-maxmod": "0.1.0",
     "romdev-platform-atari2600": "0.6.0",