romdev-mcp 0.1.1

package/examples/nes/templates/shmup.c

@@ -0,0 +1,228 @@
+/* ── shmup.c — NES vertical-scrolling shooter scaffold ───────────────
+ *
+ * A complete, runnable vertical shmup baseline. Includes:
+ *   - Player ship (8x8 sprite) — d-pad moves, A fires
+ *   - 4 bullet slots + 4 enemy slots (object pools, no malloc)
+ *   - Enemy wave spawner: one enemy per ~32 frames from the top
+ *   - Linear bullet/enemy movement + AABB collision (8x8 vs 8x8)
+ *   - Score (16-bit, packed BCD-ish) in zero page; not yet rendered
+ *
+ * The scaffold is GENRE-shaped — gameplay-specific tuning (enemy
+ * patterns, scoring rules, art) is yours to fill in. Tile data here
+ * is intentionally minimal (3 outlined boxes for ship/bullet/enemy);
+ * replace with your real sprites.
+ *
+ * Frame budget (NTSC): 60 fps × ~3 collision checks per bullet =
+ * 4 bullets × 4 enemies = 16 checks/frame. Well under the cycle budget.
+ *
+ * Read TROUBLESHOOTING.md before editing — the two-vblank PPU warm-up,
+ * shadow_oam staging-before-NMI-fires, and palette-at-$3F00 are the
+ * NES gotchas you'll trip on first.
+ */
+
+#include "nes_runtime.h"
+
+/* ── Tile data: ship (1), bullet (2), enemy (3) ──────────────────── */
+/* Each 8x8 tile is 16 bytes: 8 plane-0 bytes then 8 plane-1 bytes.
+ * Plane-0 only sets give color index 1 (palette entry 1). */
+static const uint8_t tile_blank[16] = { 0 };
+static const uint8_t tile_ship[16] = {
+  0x18, 0x3C, 0x7E, 0xFF, 0xFF, 0x7E, 0x3C, 0x18,  /* plane 0 */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_bullet[16] = {
+  0x00, 0x18, 0x3C, 0x3C, 0x3C, 0x3C, 0x18, 0x00,  /* plane 0 */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_enemy[16] = {
+  0x81, 0x42, 0x24, 0xFF, 0xFF, 0x24, 0x42, 0x81,  /* plane 0 — spider-ish */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+
+/* ── Palette ─────────────────────────────────────────────────────── */
+static const uint8_t palette[32] = {
+  /* BG (unused but PPU reads $3F00 backdrop) */
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  0x0F, 0x10, 0x20, 0x30,
+  /* Sprite palettes 0..3 */
+  0x0F, 0x21, 0x32, 0x30,  /* sp0: ship — blue/white */
+  0x0F, 0x37, 0x27, 0x16,  /* sp1: bullet — yellow */
+  0x0F, 0x16, 0x06, 0x36,  /* sp2: enemy — red */
+  0x0F, 0x2A, 0x1A, 0x0A,
+};
+
+/* ── Object pools ────────────────────────────────────────────────── */
+#define MAX_BULLETS 4
+#define MAX_ENEMIES 4
+#define TILE_SHIP    1
+#define TILE_BULLET  2
+#define TILE_ENEMY   3
+#define SHIP_PAL     0
+#define BULLET_PAL   1
+#define ENEMY_PAL    2
+
+static uint8_t bullet_active[MAX_BULLETS];
+static uint8_t bullet_x[MAX_BULLETS];
+static uint8_t bullet_y[MAX_BULLETS];
+
+static uint8_t enemy_active[MAX_ENEMIES];
+static uint8_t enemy_x[MAX_ENEMIES];
+static uint8_t enemy_y[MAX_ENEMIES];
+
+/* ── Game state ──────────────────────────────────────────────────── */
+static uint8_t ship_x = 120;
+static uint8_t ship_y = 200;
+static uint8_t fire_cooldown = 0;
+static uint8_t spawn_timer = 0;
+static uint16_t score = 0;
+static uint16_t rng = 0xACE1;  /* simple xorshift seed */
+
+/* xorshift16 — cheap LFSR-quality randomness, ~$10 cycles per call. */
+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 fire_bullet(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_BULLETS; i++) {
+    if (!bullet_active[i]) {
+      bullet_active[i] = 1;
+      bullet_x[i] = ship_x;
+      bullet_y[i] = ship_y - 4;
+      return;
+    }
+  }
+}
+
+static void spawn_enemy(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_ENEMIES; i++) {
+    if (!enemy_active[i]) {
+      enemy_active[i] = 1;
+      enemy_x[i] = 16 + (random8() & 0x7F);  /* 16..143 */
+      enemy_y[i] = 0;
+      return;
+    }
+  }
+}
+
+/* AABB 8x8 vs 8x8 — both objects assumed 8-pixel boxes. */
+static uint8_t hits(uint8_t ax, uint8_t ay, uint8_t bx, uint8_t by) {
+  uint8_t dx, dy;
+  dx = (ax > bx) ? (ax - bx) : (bx - ax);
+  dy = (ay > by) ? (ay - by) : (by - ay);
+  return (dx < 8) && (dy < 8);
+}
+
+void main(void) {
+  uint8_t i, pad, prev_pad = 0;
+
+  ppu_off();
+
+  /* Upload tile data — blank in slot 0 + 3 sprite tiles in slots 1..3. */
+  chr_ram_upload(0x0000, tile_blank,  16);
+  chr_ram_upload(0x0010, tile_ship,   16);
+  chr_ram_upload(0x0020, tile_bullet, 16);
+  chr_ram_upload(0x0030, tile_enemy,  16);
+
+  palette_load(palette);
+
+  oam_clear();
+  ppu_on_all();
+  sound_init();
+
+  /* Initialize pools to inactive. */
+  for (i = 0; i < MAX_BULLETS; i++) bullet_active[i] = 0;
+  for (i = 0; i < MAX_ENEMIES; i++) enemy_active[i] = 0;
+
+  for (;;) {
+    /* ── Stage sprites BEFORE ppu_wait_nmi() ─────────────────────
+     * ⚠ ORDER IS LOAD-BEARING. The NMI handler DMAs shadow OAM →
+     * real OAM at the START of vblank, copying whatever shadow OAM
+     * holds AT THAT MOMENT. So stage (oam_clear + oam_spr) FIRST,
+     * THEN ppu_wait_nmi(). If you flip it (wait, then stage), the
+     * frame the player sees lags one frame behind / shows stale or
+     * empty sprites. Keep oam_* above the wait. */
+    oam_clear();
+    oam_spr(ship_x, ship_y, TILE_SHIP, SHIP_PAL);
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (bullet_active[i]) {
+        oam_spr(bullet_x[i], bullet_y[i], TILE_BULLET, BULLET_PAL);
+      }
+    }
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      if (enemy_active[i]) {
+        oam_spr(enemy_x[i], enemy_y[i], TILE_ENEMY, ENEMY_PAL);
+      }
+    }
+
+    ppu_wait_nmi();
+
+    /* ── Input ───────────────────────────────────────────────── */
+    pad = pad_poll(0);
+    if ((pad & PAD_LEFT)  && ship_x > 8)   --ship_x;
+    if ((pad & PAD_RIGHT) && ship_x < 240) ++ship_x;
+    if ((pad & PAD_UP)    && ship_y > 16)  --ship_y;
+    if ((pad & PAD_DOWN)  && ship_y < 216) ++ship_y;
+
+    if ((pad & PAD_A) && fire_cooldown == 0) {
+      fire_bullet();
+      fire_cooldown = 8;  /* 8-frame cooldown */
+      sound_play_tone(0, 0x100, 6, 4);  /* short pew */
+    }
+    if (fire_cooldown > 0) --fire_cooldown;
+    prev_pad = pad;
+
+    /* ── Update bullets (move up, despawn off-screen) ────────── */
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (!bullet_active[i]) continue;
+      if (bullet_y[i] < 4) {
+        bullet_active[i] = 0;
+      } else {
+        bullet_y[i] -= 4;
+      }
+    }
+
+    /* ── Update enemies (move down, despawn off-screen) ──────── */
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      if (!enemy_active[i]) continue;
+      if (enemy_y[i] >= 232) {
+        enemy_active[i] = 0;
+      } else {
+        ++enemy_y[i];
+      }
+    }
+
+    /* ── Collisions: bullets ↔ enemies ───────────────────────── */
+    {
+      uint8_t b, e;
+      for (b = 0; b < MAX_BULLETS; b++) {
+        if (!bullet_active[b]) continue;
+        for (e = 0; e < MAX_ENEMIES; e++) {
+          if (!enemy_active[e]) continue;
+          if (hits(bullet_x[b], bullet_y[b], enemy_x[e], enemy_y[e])) {
+            bullet_active[b] = 0;
+            enemy_active[e] = 0;
+            ++score;  /* TODO: render score */
+            sound_play_noise(8, 8, 6);  /* period 8, vol 8, 6 frames */
+            break;
+          }
+        }
+      }
+    }
+
+    /* ── Spawner: one enemy every ~32 frames ─────────────────── */
+    ++spawn_timer;
+    if (spawn_timer >= 32) {
+      spawn_timer = 0;
+      spawn_enemy();
+    }
+  }
+}

package/examples/nes/templates/sports.c

@@ -0,0 +1,205 @@
+/* ── sports.c — NES two-player Pong scaffold ─────────────────────────
+ *
+ * A complete two-player Pong baseline. Both ports are wired:
+ *   - Port 0 (player 1, left paddle) — UP/DOWN move
+ *   - Port 1 (player 2, right paddle) — UP/DOWN move
+ *   - Ball bounces off paddles + top/bottom walls
+ *   - Miss → ball respawns at centre, opponent scores
+ *   - Per-side score in the top corners as ASCII digits via OAM
+ *
+ * Designed for the romdev playtest window: with two USB
+ * controllers plugged in, both players can play live. With one
+ * controller, the keyboard arrow keys drive port 0 (player 1) and
+ * port 1 acts as a wall-bot AI so single-player still works.
+ *
+ * Frame budget (NTSC): 60 fps × paddle moves × 1 ball update +
+ * 2 collision checks = negligible. Easily fits in vblank.
+ *
+ * Read TROUBLESHOOTING.md before editing — same NES gotchas as the
+ * other scaffolds (two-vblank PPU warm-up, shadow_oam staging, palette
+ * at $3F00).
+ */
+
+#include "nes_runtime.h"
+
+/* ── Tile data ────────────────────────────────────────────────────── */
+static const uint8_t tile_blank[16]  = { 0 };
+/* 8×8 paddle = solid white column (4 pixels wide centered) */
+static const uint8_t tile_paddle[16] = {
+  0x3C, 0x3C, 0x3C, 0x3C, 0x3C, 0x3C, 0x3C, 0x3C,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+/* 8×8 ball = small filled box */
+static const uint8_t tile_ball[16] = {
+  0x00, 0x3C, 0x7E, 0x7E, 0x7E, 0x7E, 0x3C, 0x00,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+/* Digits 0-9 (3 wide × 5 tall, padded to 8×8). Used for the score HUD. */
+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,
+};
+
+/* Tile indices (after upload to CHR-RAM at slot 0..). */
+#define T_BLANK   0
+#define T_PADDLE  1
+#define T_BALL    2
+#define T_DIGIT0  3   /* digits live at slots 3..12 */
+
+static const uint8_t palette[32] = {
+  /* BG palettes — only the backdrop matters here */
+  0x0F, 0x30, 0x10, 0x00,
+  0x0F, 0x30, 0x10, 0x00,
+  0x0F, 0x30, 0x10, 0x00,
+  0x0F, 0x30, 0x10, 0x00,
+  /* Sprite palettes */
+  0x0F, 0x30, 0x16, 0x12,  /* sp0: white paddle */
+  0x0F, 0x30, 0x16, 0x12,  /* sp1: white ball   */
+  0x0F, 0x30, 0x16, 0x12,
+  0x0F, 0x30, 0x16, 0x12,
+};
+
+/* Game state (fixed-point Y in 1/16-px units). */
+static int16_t p1y, p2y;       /* paddle top Y in pixels */
+static int16_t bx, by;         /* ball x, y in pixels */
+static int8_t  bdx, bdy;       /* ball velocity */
+static uint8_t score_p1, score_p2;
+static uint8_t serve_timer;
+
+#define PADDLE_H   24
+#define PADDLE_X1  16
+#define PADDLE_X2  232
+#define COURT_TOP  16
+#define COURT_BOT  216
+#define BALL_W     8
+#define BALL_H     8
+
+static void serve_ball(uint8_t to_left) {
+  bx = 128;
+  by = 112;
+  bdx = to_left ? -2 : 2;
+  /* Alternate vertical direction each serve. */
+  bdy = (score_p1 + score_p2) & 1 ? -1 : 1;
+  serve_timer = 30;
+}
+
+static void reset_match(void) {
+  p1y = 100; p2y = 100;
+  score_p1 = 0; score_p2 = 0;
+  serve_ball(0);
+}
+
+void main(void) {
+  uint8_t i;
+  uint8_t p1, p2;
+
+  ppu_off();
+
+  /* Upload tiles. */
+  chr_ram_upload(T_BLANK   * 16, tile_blank,  16);
+  chr_ram_upload(T_PADDLE  * 16, tile_paddle, 16);
+  chr_ram_upload(T_BALL    * 16, tile_ball,   16);
+  chr_ram_upload(T_DIGIT0  * 16, tile_digits, sizeof(tile_digits));
+
+  palette_load(palette);
+  oam_clear();
+  ppu_on_all();
+  sound_init();
+
+  reset_match();
+
+  for (;;) {
+    /* Stage OAM. Paddles are 3 sprites stacked (24px tall = 3×8).
+     * Ball is one sprite. Score digits use 1 sprite each. */
+    oam_clear();
+    /* Paddle 1 — left side */
+    for (i = 0; i < PADDLE_H / 8; i++)
+      oam_spr(PADDLE_X1, (uint8_t)(p1y + i * 8), T_PADDLE, 0);
+    /* Paddle 2 — right side */
+    for (i = 0; i < PADDLE_H / 8; i++)
+      oam_spr(PADDLE_X2, (uint8_t)(p2y + i * 8), T_PADDLE, 1);
+    /* Ball */
+    oam_spr((uint8_t)bx, (uint8_t)by, T_BALL, 0);
+    /* Scores — single digit each (0..9 only; extend if you want
+     * multi-digit). */
+    oam_spr(48,  4, (uint8_t)(T_DIGIT0 + score_p1), 0);
+    oam_spr(200, 4, (uint8_t)(T_DIGIT0 + score_p2), 1);
+
+    ppu_wait_nmi();
+
+    /* ── Input ────────────────────────────────────────────────── */
+    p1 = pad_poll(0);
+    p2 = pad_poll(1);
+
+    if (p1 & PAD_UP    && p1y > COURT_TOP) p1y -= 2;
+    if (p1 & PAD_DOWN  && p1y < COURT_BOT - PADDLE_H) p1y += 2;
+
+    /* Wall-bot AI on port 1 when no second controller — pad_poll(1)
+     * returns 0 when no controller is connected. Detect by sampling
+     * a few frames; here we simply fall back to AI when no buttons
+     * are ever pressed. Simpler: always run AI as a *fallback*
+     * — if p2 pressed anything this frame, use the human input. */
+    if (p2 != 0) {
+      if (p2 & PAD_UP    && p2y > COURT_TOP) p2y -= 2;
+      if (p2 & PAD_DOWN  && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+    } else {
+      /* AI: chase the ball Y, biased toward ball-direction. */
+      int16_t target = by - PADDLE_H / 2;
+      if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
+      else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
+    }
+
+    /* ── Ball update ──────────────────────────────────────────── */
+    if (serve_timer > 0) {
+      serve_timer--;
+    } else {
+      bx += bdx;
+      by += bdy;
+
+      /* Top/bottom wall bounce. */
+      if (by < COURT_TOP) { by = COURT_TOP; bdy = -bdy; sound_play_tone(1, 0x100, 8, 4); }
+      if (by + BALL_H > COURT_BOT) { by = COURT_BOT - BALL_H; bdy = -bdy; sound_play_tone(1, 0x100, 8, 4); }
+
+      /* Paddle 1 collision (left). */
+      if (bdx < 0
+          && bx <= PADDLE_X1 + 8
+          && bx + BALL_W >= PADDLE_X1
+          && by + BALL_H > p1y
+          && by < p1y + PADDLE_H) {
+        bdx = -bdx;
+        bx = PADDLE_X1 + 8;
+        sound_play_tone(0, 0x150, 8, 4);
+      }
+      /* Paddle 2 collision (right). */
+      if (bdx > 0
+          && bx + BALL_W >= PADDLE_X2
+          && bx <= PADDLE_X2 + 8
+          && by + BALL_H > p2y
+          && by < p2y + PADDLE_H) {
+        bdx = -bdx;
+        bx = PADDLE_X2 - BALL_W;
+        sound_play_tone(0, 0x150, 8, 4);
+      }
+
+      /* Score: ball off either side. */
+      if (bx < 4) {
+        if (score_p2 < 9) score_p2++;
+        sound_play_noise(5, 8, 8);
+        serve_ball(0);
+      }
+      if (bx > 252) {
+        if (score_p1 < 9) score_p1++;
+        sound_play_noise(5, 8, 8);
+        serve_ball(1);
+      }
+    }
+  }
+}

package/examples/nes/templates/tile_engine.c

@@ -0,0 +1,224 @@
+/* ── tile_engine.c — NES starter with a tile map + multiple rooms ──
+ *
+ * Single-screen-per-room layout (Adventure / Zelda-1 / Sokoban shape).
+ *   - 32×30 BG nametable rendered from a `room[]` array
+ *   - Walk a sprite around with the d-pad
+ *   - Crossing the screen edge transitions to the next room
+ *   - 3 hand-written rooms wired up; extend with more for a real game
+ *
+ * Tile data layout (8×8, 2bpp NES format):
+ *   tile 0 — blank          (always reserved so OAM Y=0 doesn't glitch)
+ *   tile 1 — floor          (light pattern)
+ *   tile 2 — wall           (solid)
+ *   tile 3 — door           (different color)
+ *   tile 4 — player sprite
+ *
+ * NES BG fetches from $1000-$1FFF in the default PPUCTRL we use, so
+ * BG tiles get uploaded there. Sprite tiles go to $0000-$0FFF.
+ */
+
+#include "nes_runtime.h"
+
+/* ── Tile data ──────────────────────────────────────────────────
+ * Layout per tile: 8 bytes plane 0 + 8 bytes plane 1 = 16 bytes.
+ * For row N: byte 2N is plane-0 (low bit), byte 2N+1 (... wait no):
+ * Actually NES is INTERLEAVED differently — first 8 bytes is plane 0,
+ * second 8 bytes is plane 1.
+ *
+ *  bit value of pixel = plane0_bit + plane1_bit * 2
+ */
+static const uint8_t bg_tiles[4 * 16] = {
+  /* tile 0: blank */
+  0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,
+  /* tile 1: floor — light speckle pattern (color 1) */
+  0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA,
+  0,    0,    0,    0,    0,    0,    0,    0,
+  /* tile 2: wall — solid (color 3, both planes set) */
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  /* tile 3: door — outline color 2 */
+  0xFF, 0x81, 0x81, 0x81, 0x81, 0x81, 0x81, 0xFF,
+  0xFF, 0x81, 0x81, 0x81, 0x81, 0x81, 0x81, 0xFF,
+};
+
+static const uint8_t spr_tiles[1 * 16] = {
+  /* tile 0: blank */
+  0,0,0,0,0,0,0,0, 0,0,0,0,0,0,0,0,
+};
+
+static const uint8_t player_tile[16] = {
+  /* outline color 3, fill color 0 */
+  0x3C, 0x42, 0x81, 0x81, 0x81, 0x81, 0x42, 0x3C,
+  0x3C, 0x42, 0x81, 0x81, 0x81, 0x81, 0x42, 0x3C,
+};
+
+static const uint8_t palette[32] = {
+  /* BG palettes — 0 used for the room */
+  0x0F, 0x10, 0x06, 0x16,    /* dark grey backdrop, light grey floor, brown walls */
+  0x0F, 0x21, 0x11, 0x01,
+  0x0F, 0x27, 0x17, 0x07,
+  0x0F, 0x2A, 0x1A, 0x0A,
+  /* Sprite palettes — 0 used for player */
+  0x0F, 0x2C, 0x14, 0x20,    /* transparent, cyan, magenta, white */
+  0x0F, 0x21, 0x11, 0x01,
+  0x0F, 0x27, 0x17, 0x07,
+  0x0F, 0x2A, 0x1A, 0x0A,
+};
+
+/* ── Rooms ──────────────────────────────────────────────────────
+ * 32 columns × 30 rows = 960 tiles. Tile index per cell. Edges are
+ * walls (tile 2). One door per side leads to the next room.
+ */
+#define COLS 32
+#define ROWS 30
+#define ROOMS 3
+
+/* For a real game these would be byte arrays. For brevity here we
+ * fill rooms procedurally based on the room index.
+ */
+
+/* Get the tile that should appear at (x, y) in room `r`. */
+static uint8_t room_tile(uint8_t r, uint8_t x, uint8_t y) {
+  /* Edges = wall. */
+  if (x == 0 || x == COLS - 1 || y == 0 || y == ROWS - 1) {
+    /* Doors: right edge of room 0/1, left edge of room 1/2. */
+    if (y >= 14 && y <= 15) {
+      if (x == COLS - 1 && r < ROOMS - 1) return 3;
+      if (x == 0 && r > 0) return 3;
+    }
+    return 2;
+  }
+  /* Interior decor varies per room. */
+  if (r == 1) {
+    /* Pillars in room 1. */
+    if ((x == 6 || x == 14 || x == 22 || x == 26) && y == 14) return 2;
+  }
+  if (r == 2) {
+    /* Cross pattern. */
+    if (x == 15 && y >= 10 && y <= 20) return 2;
+    if (y == 15 && x >= 10 && x <= 21) return 2;
+  }
+  return 1;  /* floor */
+}
+
+/* Returns true if tile is solid (wall). */
+static uint8_t solid(uint8_t r, uint8_t x, uint8_t y) {
+  return (room_tile(r, x, y) == 2);
+}
+
+/* Returns true if tile is a door. */
+static uint8_t is_door(uint8_t r, uint8_t x, uint8_t y) {
+  return (room_tile(r, x, y) == 3);
+}
+
+/* Render the current room into nametable 0 ($2000) and attribute
+ * table. Caller must have PPU off. */
+static void render_room(uint8_t r) {
+  uint16_t ppu_addr = 0x2000;
+  uint8_t y, x;
+  uint8_t attr_byte;
+  uint16_t attr_addr;
+  uint8_t row, col;
+
+  /* Walk nametable cells. PPUADDR auto-increments by 1 in our default
+   * PPUCTRL, so we can stream the row at once. */
+  for (y = 0; y < ROWS; y++) {
+    for (x = 0; x < COLS; x++) {
+      vram_unsafe_set(ppu_addr, room_tile(r, x, y));
+      ++ppu_addr;
+    }
+  }
+  /* Attribute table: 8×8 grid of bytes, each covering 4×4 tile group
+   * with 4 quadrants. Use palette 0 for the entire room. */
+  attr_addr = 0x23C0;
+  attr_byte = 0x00;
+  for (row = 0; row < 8; row++) {
+    for (col = 0; col < 8; col++) {
+      vram_unsafe_set(attr_addr, attr_byte);
+      ++attr_addr;
+    }
+  }
+}
+
+void main(void) {
+  uint8_t px = 128;
+  uint8_t py = 120;
+  uint8_t current_room = 0;
+  uint8_t pad;
+  uint8_t nx, ny;
+  uint8_t tx, ty;
+
+  /* ── 1. PPU off ─────────────────────────────────────────────── */
+  ppu_off();
+
+  /* ── 2. Upload tile data ──────────────────────────────────────
+   * Sprite tiles at $0000, BG tiles at $1000 (default PPUCTRL has
+   * bit 4 set = BG pattern table at $1000). */
+  chr_ram_upload(0x0000, spr_tiles, sizeof(spr_tiles));
+  chr_ram_upload(0x0010, player_tile, 16);   /* sprite slot 1 = player */
+  chr_ram_upload(0x1000, bg_tiles, sizeof(bg_tiles));
+
+  /* ── 3. Palette ─────────────────────────────────────────────── */
+  palette_load(palette);
+
+  /* ── 4. Render starting room ────────────────────────────────── */
+  render_room(current_room);
+
+  /* ── 5. Initial OAM with player sprite ──────────────────────── */
+  oam_clear();
+  oam_spr(px, py, /* tile */ 1, /* attr */ 0);
+
+  /* ── 6. PPU back on ─────────────────────────────────────────── */
+  ppu_on_all();
+
+  /* ── 7. Game loop ───────────────────────────────────────────── */
+  for (;;) {
+    /* Stage sprite for the upcoming frame. */
+    oam_clear();
+    oam_spr(px, py, 1, 0);
+
+    /* Wait for vblank — NMI handler will DMA shadow_oam to OAM. */
+    ppu_wait_nmi();
+
+    /* Read input. */
+    pad = pad_poll(0);
+    nx = px;
+    ny = py;
+    if (pad & PAD_LEFT)  --nx;
+    if (pad & PAD_RIGHT) ++nx;
+    if (pad & PAD_UP)    --ny;
+    if (pad & PAD_DOWN)  ++ny;
+
+    /* Tile under the player's center (player is 8×8). */
+    tx = (uint8_t)(nx >> 3);
+    ty = (uint8_t)(ny >> 3);
+
+    /* Door — transition to neighbouring room. */
+    if (is_door(current_room, tx, ty)) {
+      if (nx >= 240 && current_room < ROOMS - 1) {
+        ++current_room;
+        px = 16;
+        py = ny;
+        ppu_off();
+        render_room(current_room);
+        ppu_on_all();
+        continue;
+      }
+      if (nx <= 12 && current_room > 0) {
+        --current_room;
+        px = 232;
+        py = ny;
+        ppu_off();
+        render_room(current_room);
+        ppu_on_all();
+        continue;
+      }
+    }
+
+    /* Wall collision. */
+    if (!solid(current_room, tx, ty)) {
+      px = nx;
+      py = ny;
+    }
+  }
+}