romdev-mcp 0.1.1

package/examples/nes/templates/music_demo.c

@@ -0,0 +1,80 @@
+/* ── music_demo.c — continuous-music NES starter ────────────────
+ *
+ * Bundled-driver demo: FamiTone2 (Shiru, public domain) plays a multi-
+ * channel music track from ROM. Compare to `default.c` (silent) or
+ * `hello_sprite.c` (single APU beep on button press).
+ *
+ * What ships:
+ *   famitone2.s         — the 6502 music engine (~1.5 KB of code)
+ *   famitone_bridge.s   — tiny C-callable wrappers around its entry pts
+ *   music_data.s        — the song bytes (a public-domain test track)
+ *
+ * How it works:
+ *   1. famitone_init(music_data) at boot — wires the song pointer
+ *      and resets APU channel state.
+ *   2. famitone_play(0) starts subsong 0. The track ships with two
+ *      subsongs (0 + 1); change the index to switch.
+ *   3. famitone_update() runs once per frame, right after the
+ *      ppu_wait_nmi() heartbeat. This is the engine's tick — it
+ *      walks the pattern data, computes envelope values, and writes
+ *      the APU registers.
+ *
+ * APU sharing: this driver "owns" $4000-$4007 (pulse 1+2),
+ * $4008-$400B (triangle), $400C-$400F (noise) while it's running.
+ * If you want SFX too, swap in famitone2's SFX mode (FT_SFX_ENABLE
+ * in famitone2.s) and call its sfx APIs from C via a similar bridge.
+ *
+ * To swap the song:
+ *   - Export your FamiTracker module as .txt
+ *   - Run text2data on it (see LICENSE-FAMITONE for the source repo)
+ *   - Paste the generated bytes into music_data.s (keep the label).
+ */
+
+#include "nes_runtime.h"
+
+/* Imported from famitone_bridge.s (the cc65-fastcall wrappers around
+ * the asm engine). */
+void __fastcall__ famitone_init(const unsigned char *music_data);
+void __fastcall__ famitone_play(unsigned char song_index);
+void __fastcall__ famitone_update(void);
+
+/* music_data lives in music_data.s. */
+extern const unsigned char music_data[];
+
+static const unsigned char bg_colors[4] = { 0x0F, 0x01, 0x21, 0x31 };
+
+void main(void) {
+  unsigned char palette[32];
+  unsigned char i;
+  unsigned char shade = 0;
+  unsigned char frame = 0;
+
+  for (i = 0; i < 32; i++) palette[i] = bg_colors[0];
+
+  ppu_off();
+  palette_load(palette);
+  oam_clear();
+
+  /* Start the music BEFORE rendering — FamiToneInit takes a few
+   * hundred cycles, but it disables NMI internally only via APU regs;
+   * the PPU is unaffected. Safe to call with PPU off. */
+  famitone_init(music_data);
+  famitone_play(0);
+
+  ppu_on_all();
+
+  for (;;) {
+    ppu_wait_nmi();
+    /* Drive the music engine once per frame. FamiTone2's docs call
+     * for invocation from the NMI itself; calling it here (right
+     * after the NMI returns) is equivalent for music-only use and
+     * keeps the engine out of the vblank-critical path. */
+    famitone_update();
+
+    ++frame;
+    if ((frame & 0x1F) == 0) {       /* every 32 frames */
+      shade = (unsigned char)((shade + 1) & 0x03);
+      vram_set(0x3F00, bg_colors[shade]);
+    }
+  }
+}

package/examples/nes/templates/platformer.c

@@ -0,0 +1,171 @@
+/* ── platformer.c — NES single-screen platformer scaffold ────────────
+ *
+ * A complete, runnable platformer baseline. Includes:
+ *   - Player (8x8 sprite) — d-pad LEFT/RIGHT moves, A jumps
+ *   - Gravity + jump physics with fixed-point Y (Q4.4: 4 frac bits)
+ *   - Static platform list (5 horizontal rects) — collide-from-above only
+ *   - Walk + jump animation via tile-id swapping
+ *   - Right-edge → "you win" silence; fall off bottom → respawn
+ *
+ * Why fixed-point Y: gravity adds < 1 pixel/frame at peak jump, so we
+ * need sub-pixel precision. X stays integer because horizontal motion
+ * is integer-speed (no acceleration). Standard NES platformer trick.
+ *
+ * Collision is rect-vs-rect "land on top" only — no side-collision,
+ * no head-bump-stop. Add those when your scaffold proves out. This
+ * keeps the baseline understandable + extendable.
+ *
+ * SINGLE-SCREEN as shipped (platforms are drawn as SPRITES, not BG).
+ * To make it a SIDE-SCROLLER you must draw platforms into the BACKGROUND
+ * nametables (so hardware scroll moves them), use ppu_scroll(camX, 0) —
+ * which flips the PPUCTRL nametable-select bit past 256 px for you — and
+ * for a world wider than 512 px stream a fresh nametable column + its
+ * attribute byte into the off-screen nametable each 8-px camera step.
+ * The chr-ram-runtime crt0 uses VERTICAL mirroring, giving NT0 (left) +
+ * NT1 (right) side by side = a free 512-px world. See the NES
+ * MENTAL_MODEL.md "Backgrounds" + "NMI" sections.
+ */
+
+#include "nes_runtime.h"
+
+/* ── Tiles: player idle/jump + platform block ────────────────────── */
+static const uint8_t tile_blank[16] = { 0 };
+static const uint8_t tile_player_idle[16] = {
+  0x3C, 0x7E, 0xFF, 0xFF, 0xFF, 0xFF, 0x7E, 0x3C,  /* plane 0 — round blob */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_player_jump[16] = {
+  0x18, 0x7E, 0xFF, 0xFF, 0xE7, 0xC3, 0x81, 0x00,  /* plane 0 — arms up */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_platform[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,  /* plane 0 — solid */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+
+static const uint8_t palette[32] = {
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x21, 0x32, 0x30,  /* sp0: player — blue */
+  0x0F, 0x18, 0x28, 0x38,  /* sp1: platforms — green */
+  0x0F, 0x16, 0x06, 0x36,
+  0x0F, 0x2A, 0x1A, 0x0A,
+};
+
+/* ── Platforms (static rectangles) ───────────────────────────────── */
+typedef struct { uint8_t x, y, w; } Platform;  /* 8 px tall, w in tiles */
+#define NUM_PLATFORMS 5
+static const Platform platforms[NUM_PLATFORMS] = {
+  {  16, 200, 20 },  /* ground band */
+  {  40, 168,  4 },
+  { 104, 144,  4 },
+  { 168, 168,  4 },
+  { 200, 120,  4 },
+};
+
+#define TILE_PLAYER_IDLE  1
+#define TILE_PLAYER_JUMP  2
+#define TILE_PLATFORM     3
+#define PLAYER_PAL        0
+#define PLATFORM_PAL      1
+
+/* ── Player state ────────────────────────────────────────────────── */
+static uint8_t  px = 24;
+static uint16_t py_q44 = (200 - 8) << 4;  /* Q4.4 — start above leftmost platform */
+static int8_t   vy_q44 = 0;
+static uint8_t  on_ground = 0;
+
+#define GRAVITY_Q44    1   /* +1/16 px per frame per frame */
+#define JUMP_VEL_Q44 (-40) /* initial vy → peak ~5 tile jump */
+#define MOVE_SPEED     1   /* 1 px / frame */
+
+/* AABB: player rect vs platform top edge (treat platform as 8 px tall). */
+static uint8_t landed_on(uint8_t pl_idx, uint8_t player_y) {
+  const Platform *p = &platforms[pl_idx];
+  uint8_t feet_y = player_y + 7;
+  if (feet_y < p->y || feet_y > p->y + 4) return 0;          /* not at top edge */
+  if (px + 7 < p->x) return 0;
+  if (px > p->x + (p->w << 3) - 1) return 0;
+  return 1;
+}
+
+void main(void) {
+  uint8_t pad, prev_pad = 0;
+  uint8_t player_y, i;
+
+  ppu_off();
+
+  chr_ram_upload(0x0000, tile_blank,        16);
+  chr_ram_upload(0x0010, tile_player_idle,  16);
+  chr_ram_upload(0x0020, tile_player_jump,  16);
+  chr_ram_upload(0x0030, tile_platform,     16);
+
+  palette_load(palette);
+
+  oam_clear();
+  ppu_on_all();
+  sound_init();
+
+  for (;;) {
+    player_y = (uint8_t)(py_q44 >> 4);
+
+    /* ── Stage sprites BEFORE ppu_wait_nmi() ────────────────────
+     * The NMI handler DMAs shadow OAM at vblank-start, so oam_clear +
+     * oam_spr MUST run before the wait below — flip the order and the
+     * visible frame lags / shows stale sprites. */
+    oam_clear();
+    /* player tile depends on whether airborne */
+    oam_spr(px, player_y,
+            on_ground ? TILE_PLAYER_IDLE : TILE_PLAYER_JUMP,
+            PLAYER_PAL);
+    /* draw each platform tile (one OAM entry per 8 px column) */
+    for (i = 0; i < NUM_PLATFORMS; i++) {
+      uint8_t k;
+      for (k = 0; k < platforms[i].w; k++) {
+        oam_spr(platforms[i].x + (k << 3), platforms[i].y, TILE_PLATFORM, PLATFORM_PAL);
+      }
+    }
+
+    ppu_wait_nmi();
+
+    /* ── Input ──────────────────────────────────────────────── */
+    pad = pad_poll(0);
+    if ((pad & PAD_LEFT)  && px > 8)   px -= MOVE_SPEED;
+    if ((pad & PAD_RIGHT) && px < 240) px += MOVE_SPEED;
+    /* Jump on rising-edge of A while on ground. */
+    if ((pad & PAD_A) && !(prev_pad & PAD_A) && on_ground) {
+      vy_q44 = JUMP_VEL_Q44;
+      on_ground = 0;
+      sound_play_tone(0, 0x150, 6, 6);
+    }
+    prev_pad = pad;
+
+    /* ── Physics ────────────────────────────────────────────── */
+    /* gravity */
+    if (vy_q44 < 80) vy_q44 += GRAVITY_Q44;  /* terminal velocity */
+    py_q44 += vy_q44;
+
+    /* ── Ground / platform collision (descending only) ──────── */
+    on_ground = 0;
+    if (vy_q44 >= 0) {                       /* falling */
+      for (i = 0; i < NUM_PLATFORMS; i++) {
+        if (landed_on(i, (uint8_t)(py_q44 >> 4))) {
+          py_q44 = (platforms[i].y - 8) << 4;
+          vy_q44 = 0;
+          on_ground = 1;
+          break;
+        }
+      }
+    }
+
+    /* ── Off-bottom → respawn at top-left ───────────────────── */
+    if ((py_q44 >> 4) >= 232) {
+      px = 24;
+      py_q44 = 100 << 4;
+      vy_q44 = 0;
+      sound_play_noise(8, 8, 8);  /* respawn buzz */
+    }
+  }
+}

package/examples/nes/templates/puzzle.c

@@ -0,0 +1,232 @@
+/* ── puzzle.c — NES match-3 falling-block scaffold ──────────────────
+ *
+ * A Columns/Tetris-ish baseline. Includes:
+ *   - 6x12 grid in CHR-RAM-rendered "blocks" (sprites, not BG, so we
+ *     can move pieces without an attribute-table refresh dance)
+ *   - 1 active piece (a 1x3 vertical column of three colored blocks)
+ *   - d-pad LEFT/RIGHT moves the piece, DOWN soft-drops, A rotates
+ *     (cycles the 3 colors of the active piece)
+ *   - Auto-fall every 30 frames (~0.5s)
+ *   - Match-3 horizontal detection — clears horizontally aligned
+ *     triples of the same color. Add vertical + diagonal as exercise.
+ *
+ * Scope-shaped choice: we render every block as a sprite (one OAM
+ * entry per occupied cell). 6×12 = 72 sprites max — well under the 64
+ * hardware sprite limit per scanline, but at the edge of NES per-frame
+ * total. A real puzzle game would render the well in the BG nametable
+ * and only the active piece as sprites. Keeping it all-sprites here
+ * trades 8-sprites-per-scanline flicker for code simplicity. Profile
+ * before optimizing.
+ */
+
+#include "nes_runtime.h"
+
+#define GRID_W 6
+#define GRID_H 12
+#define ORIGIN_X 80   /* px — leftmost column anchor */
+#define ORIGIN_Y 16   /* px — top row anchor */
+#define CELL_PX  8    /* one tile per cell */
+
+#define EMPTY    0
+#define COL_R    1
+#define COL_G    2
+#define COL_B    3
+
+#define TILE_BLOCK_R  1
+#define TILE_BLOCK_G  2
+#define TILE_BLOCK_B  3
+
+/* ── Tiles: 3 colored 8x8 blocks ─────────────────────────────────── */
+static const uint8_t tile_blank[16] = { 0 };
+/* All three blocks use the same shape, but different palette indices.
+ * We achieve that by varying the plane bits: plane0=1 → idx 1 (R),
+ * plane1=1 → idx 2 (G), both planes set → idx 3 (B). */
+static const uint8_t tile_block_r[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_block_g[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+};
+static const uint8_t tile_block_b[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+};
+
+static const uint8_t palette[32] = {
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  /* Sprite palette 0: idx1=red, idx2=green, idx3=blue */
+  0x0F, 0x16, 0x1A, 0x12,
+  0x0F, 0x16, 0x1A, 0x12,
+  0x0F, 0x16, 0x1A, 0x12,
+  0x0F, 0x16, 0x1A, 0x12,
+};
+
+/* ── State ───────────────────────────────────────────────────────── */
+static uint8_t grid[GRID_H][GRID_W];      /* 0 = empty, 1..3 = color */
+static uint8_t piece_x = GRID_W / 2;       /* column 0..GRID_W-1 */
+static int8_t  piece_y = -3;               /* row; piece is 3 cells tall above this y */
+static uint8_t piece_col[3] = { COL_R, COL_G, COL_B };  /* top, mid, bot */
+static uint8_t fall_timer = 0;
+static uint16_t rng = 0xBEEF;
+
+static uint8_t random8(void) {
+  uint16_t r = rng;
+  r ^= r << 7;
+  r ^= r >> 9;
+  r ^= r << 8;
+  rng = r;
+  return (uint8_t)r;
+}
+
+static void random_piece_colors(void) {
+  piece_col[0] = 1 + (random8() % 3);
+  piece_col[1] = 1 + (random8() % 3);
+  piece_col[2] = 1 + (random8() % 3);
+}
+
+static uint8_t tile_for_color(uint8_t col) {
+  switch (col) {
+    case COL_R: return TILE_BLOCK_R;
+    case COL_G: return TILE_BLOCK_G;
+    case COL_B: return TILE_BLOCK_B;
+    default:    return 0;
+  }
+}
+
+static void spawn_piece(void) {
+  piece_x = GRID_W / 2;
+  piece_y = -3;
+  random_piece_colors();
+}
+
+/* Lock current piece into the grid + check for match-3 horizontals. */
+static void lock_piece(void) {
+  uint8_t r, c, run, run_col;
+  int8_t i;
+  /* Drop the 3 cells into the grid. */
+  for (i = 0; i < 3; i++) {
+    int8_t y = piece_y + i;
+    if (y >= 0 && y < GRID_H) {
+      grid[y][piece_x] = piece_col[i];
+    }
+  }
+  /* Scan each row for 3-in-a-row same color → clear. */
+  for (r = 0; r < GRID_H; r++) {
+    run = 1;
+    run_col = grid[r][0];
+    for (c = 1; c < GRID_W; c++) {
+      if (grid[r][c] == run_col && run_col != EMPTY) {
+        ++run;
+        if (run >= 3) {
+          /* Found a triple ending at c — clear back. */
+          grid[r][c]     = EMPTY;
+          grid[r][c - 1] = EMPTY;
+          grid[r][c - 2] = EMPTY;
+          sound_play_tone(0, 0x100 - (c << 4), 6, 4);
+        }
+      } else {
+        run = 1;
+        run_col = grid[r][c];
+      }
+    }
+  }
+}
+
+/* Can the piece occupy (x, y..y+2) given the current grid? */
+static uint8_t can_place(int8_t x, int8_t y) {
+  int8_t i;
+  if (x < 0 || x >= GRID_W) return 0;
+  for (i = 0; i < 3; i++) {
+    int8_t cy = y + i;
+    if (cy < 0) continue;          /* above the well — allowed */
+    if (cy >= GRID_H) return 0;     /* below the well — blocked */
+    if (grid[cy][x] != EMPTY) return 0;
+  }
+  return 1;
+}
+
+void main(void) {
+  uint8_t pad, prev_pad = 0;
+  uint8_t r, c;
+  int8_t  i;
+
+  ppu_off();
+  chr_ram_upload(0x0000, tile_blank,    16);
+  chr_ram_upload(0x0010, tile_block_r,  16);
+  chr_ram_upload(0x0020, tile_block_g,  16);
+  chr_ram_upload(0x0030, tile_block_b,  16);
+  palette_load(palette);
+  oam_clear();
+  ppu_on_all();
+  sound_init();
+
+  for (r = 0; r < GRID_H; r++)
+    for (c = 0; c < GRID_W; c++) grid[r][c] = EMPTY;
+  spawn_piece();
+
+  for (;;) {
+    /* ── Stage sprites: every non-empty cell + the active piece ── */
+    oam_clear();
+    for (r = 0; r < GRID_H; r++) {
+      for (c = 0; c < GRID_W; c++) {
+        if (grid[r][c] != EMPTY) {
+          oam_spr(
+            ORIGIN_X + c * CELL_PX,
+            ORIGIN_Y + r * CELL_PX,
+            tile_for_color(grid[r][c]),
+            0);
+        }
+      }
+    }
+    for (i = 0; i < 3; i++) {
+      int8_t y = piece_y + i;
+      if (y >= 0 && y < GRID_H) {
+        oam_spr(
+          ORIGIN_X + piece_x * CELL_PX,
+          ORIGIN_Y + y * CELL_PX,
+          tile_for_color(piece_col[i]),
+          0);
+      }
+    }
+
+    ppu_wait_nmi();
+
+    /* ── Input ──────────────────────────────────────────────── */
+    pad = pad_poll(0);
+    if ((pad & PAD_LEFT)  && !(prev_pad & PAD_LEFT)  && can_place(piece_x - 1, piece_y)) --piece_x;
+    if ((pad & PAD_RIGHT) && !(prev_pad & PAD_RIGHT) && can_place(piece_x + 1, piece_y)) ++piece_x;
+    /* A: rotate (cycle the 3 colors) */
+    if ((pad & PAD_A) && !(prev_pad & PAD_A)) {
+      uint8_t tmp = piece_col[0];
+      piece_col[0] = piece_col[1];
+      piece_col[1] = piece_col[2];
+      piece_col[2] = tmp;
+    }
+    /* DOWN: soft-drop (faster fall) */
+    if (pad & PAD_DOWN) fall_timer += 4;
+    prev_pad = pad;
+
+    /* ── Auto-fall ──────────────────────────────────────────── */
+    ++fall_timer;
+    if (fall_timer >= 30) {
+      fall_timer = 0;
+      if (can_place(piece_x, piece_y + 1)) {
+        ++piece_y;
+      } else {
+        lock_piece();
+        spawn_piece();
+        /* Game over: piece can't be placed at spawn. Just reset grid. */
+        if (!can_place(piece_x, piece_y)) {
+          for (r = 0; r < GRID_H; r++)
+            for (c = 0; c < GRID_W; c++) grid[r][c] = EMPTY;
+          sound_play_noise(8, 8, 12);  /* game-over buzz */
+        }
+      }
+    }
+  }
+}

package/examples/nes/templates/racing.c

@@ -0,0 +1,203 @@
+/* ── racing.c — NES top-down racing scaffold ─────────────────────────
+ *
+ * A simple endless top-down racer. Player car at the bottom; the
+ * "road" scrolls down as obstacles (other cars) come up from the top.
+ * Left/Right or A/B switches between three lanes. Survive as long as
+ * possible — score = frames survived.
+ *
+ * Mechanics:
+ *   - 3 lanes (left / centre / right)
+ *   - 4 obstacle slots (object pool) — one spawns from a random lane
+ *     every ~40 frames
+ *   - Obstacles slide down at constant speed
+ *   - AABB collision; on hit, game-over state pauses for 60 frames then
+ *     resets the run
+ *   - Score = frames-survived-in-current-run, rendered with the
+ *     digit tiles
+ *
+ * Two-player mode: port 1 (player 2) controls a second car in
+ * the opposite half of the screen. When no second controller is
+ * present, P2 lane runs an AI that dodges in the same pattern.
+ *
+ * Easy extensions: scrolling BG road stripes, scenery sprites,
+ * acceleration / brake, lap timer, multi-tier obstacle types.
+ */
+
+#include "nes_runtime.h"
+
+/* ── Tile data ────────────────────────────────────────────────────── */
+static const uint8_t tile_blank[16] = { 0 };
+/* Player car — 8×8 small box with a roof */
+static const uint8_t tile_car_p1[16] = {
+  0x3C, 0x7E, 0x42, 0x7E, 0x7E, 0x7E, 0x42, 0x66,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+/* Enemy car — inverted */
+static const uint8_t tile_car_enemy[16] = {
+  0x66, 0x42, 0x7E, 0x7E, 0x7E, 0x42, 0x7E, 0x3C,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+/* Digit tiles for the HUD (same 3×5-padded shape as sports.c). */
+static const uint8_t tile_digits[10 * 16] = {
+  /* 0 */ 0xE0,0xA0,0xA0,0xA0,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 1 */ 0x40,0xC0,0x40,0x40,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 2 */ 0xE0,0x20,0xE0,0x80,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 3 */ 0xE0,0x20,0xE0,0x20,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 4 */ 0xA0,0xA0,0xE0,0x20,0x20,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 5 */ 0xE0,0x80,0xE0,0x20,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 6 */ 0xE0,0x80,0xE0,0xA0,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 7 */ 0xE0,0x20,0x20,0x40,0x40,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 8 */ 0xE0,0xA0,0xE0,0xA0,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+  /* 9 */ 0xE0,0xA0,0xE0,0x20,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
+};
+
+#define T_BLANK     0
+#define T_CAR_P1    1
+#define T_CAR_ENEMY 2
+#define T_DIGIT0    3
+
+static const uint8_t palette[32] = {
+  /* BG palettes — light grey backdrop simulates road */
+  0x10, 0x30, 0x16, 0x12,
+  0x10, 0x30, 0x16, 0x12,
+  0x10, 0x30, 0x16, 0x12,
+  0x10, 0x30, 0x16, 0x12,
+  /* Sprite palettes */
+  0x10, 0x21, 0x16, 0x30,   /* sp0: blue car (P1) */
+  0x10, 0x16, 0x21, 0x30,   /* sp1: red enemy */
+  0x10, 0x2A, 0x21, 0x30,
+  0x10, 0x2A, 0x21, 0x30,
+};
+
+#define LANE_LEFT_X   88
+#define LANE_MID_X    120
+#define LANE_RIGHT_X  152
+#define PLAYER_Y      192
+
+#define MAX_OBSTACLES 4
+
+typedef struct { uint8_t x, y, alive; } Car;
+
+static Car   player;       /* y is fixed at PLAYER_Y; x switches lanes */
+static Car   obstacles[MAX_OBSTACLES];
+static uint16_t score;
+static uint8_t spawn_timer;
+static uint8_t game_over_timer;
+static uint8_t prev_p1;
+
+static const uint8_t lane_x[3] = { LANE_LEFT_X, LANE_MID_X, LANE_RIGHT_X };
+static uint8_t player_lane;
+
+static uint8_t aabb(Car *a, Car *b) {
+  return a->x < b->x + 8 && a->x + 8 > b->x
+      && a->y < b->y + 8 && a->y + 8 > b->y;
+}
+
+static void reset_run(void) {
+  uint8_t i;
+  player_lane = 1;
+  player.x = lane_x[1]; player.y = PLAYER_Y; player.alive = 1;
+  for (i = 0; i < MAX_OBSTACLES; i++) obstacles[i].alive = 0;
+  score = 0;
+  spawn_timer = 0;
+  game_over_timer = 0;
+}
+
+static void spawn_obstacle(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_OBSTACLES; i++) {
+    if (!obstacles[i].alive) {
+      obstacles[i].x = lane_x[(spawn_timer * 13) % 3];
+      obstacles[i].y = 0;
+      obstacles[i].alive = 1;
+      return;
+    }
+  }
+}
+
+static void render_score(void) {
+  /* Render a 5-digit decimal score as 5 OAM sprites in the top-right. */
+  uint16_t v = score;
+  uint8_t digits[5];
+  int8_t i;
+  for (i = 4; i >= 0; i--) { digits[i] = v % 10; v /= 10; }
+  for (i = 0; i < 5; i++) {
+    oam_spr((uint8_t)(192 + i * 8), 4,
+            (uint8_t)(T_DIGIT0 + digits[i]), 0);
+  }
+}
+
+void main(void) {
+  uint8_t i;
+  uint8_t p1;
+
+  ppu_off();
+
+  chr_ram_upload(T_BLANK     * 16, tile_blank,     16);
+  chr_ram_upload(T_CAR_P1    * 16, tile_car_p1,    16);
+  chr_ram_upload(T_CAR_ENEMY * 16, tile_car_enemy, 16);
+  chr_ram_upload(T_DIGIT0    * 16, tile_digits,    sizeof(tile_digits));
+
+  palette_load(palette);
+  oam_clear();
+  ppu_on_all();
+  sound_init();
+
+  reset_run();
+  prev_p1 = 0;
+
+  for (;;) {
+    oam_clear();
+    /* Player car */
+    oam_spr(player.x, player.y, T_CAR_P1, 0);
+    /* Obstacles */
+    for (i = 0; i < MAX_OBSTACLES; i++) {
+      if (obstacles[i].alive)
+        oam_spr(obstacles[i].x, obstacles[i].y, T_CAR_ENEMY, 1);
+    }
+    render_score();
+
+    ppu_wait_nmi();
+
+    p1 = pad_poll(0);
+
+    if (game_over_timer > 0) {
+      game_over_timer--;
+      if (game_over_timer == 0) reset_run();
+      prev_p1 = p1;
+      continue;
+    }
+
+    /* ── Input — switch lanes on left/right press (edge-detected). */
+    if ((p1 & PAD_LEFT) && !(prev_p1 & PAD_LEFT) && player_lane > 0) {
+      player_lane--;
+      sound_play_tone(0, 0x180, 6, 3);
+    }
+    if ((p1 & PAD_RIGHT) && !(prev_p1 & PAD_RIGHT) && player_lane < 2) {
+      player_lane++;
+      sound_play_tone(0, 0x180, 6, 3);
+    }
+    player.x = lane_x[player_lane];
+    prev_p1 = p1;
+
+    /* ── Obstacles slide down ─────────────────────────────────── */
+    for (i = 0; i < MAX_OBSTACLES; i++) {
+      if (!obstacles[i].alive) continue;
+      if (obstacles[i].y < 232) obstacles[i].y += 2;
+      else obstacles[i].alive = 0;
+    }
+    if (++spawn_timer >= 36) { spawn_timer = 0; spawn_obstacle(); }
+
+    /* Collisions */
+    for (i = 0; i < MAX_OBSTACLES; i++) {
+      if (!obstacles[i].alive) continue;
+      if (aabb(&player, &obstacles[i])) {
+        sound_play_noise(8, 8, 16);
+        game_over_timer = 60;
+        break;
+      }
+    }
+
+    if (score < 65500) score++;
+  }
+}