romdev-mcp 0.1.1

package/examples/sms/templates/shmup.c

@@ -0,0 +1,167 @@
+/* ── shmup.c — SMS vertical-shooter scaffold ────────────────────────
+ *
+ * Mirrors the NES/Genesis/SNES/GB shmup scaffolds. Player ship + 4
+ * bullet slots + 4 enemy slots, wave spawner, AABB collisions.
+ *
+ * SMS has 64 sprites max, 8 per scanline. Player at slot 0,
+ * bullets 1-4, enemies 5-8. Score kept in WRAM.
+ */
+#include "sms_hw.h"
+#include "sms_sfx.h"
+#include <stdint.h>
+
+extern void sms_vdp_init(void);
+extern void sms_vdp_display_on(void);
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+extern void sms_load_palette(const uint8_t *palette);
+extern void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void sms_vblank_wait(void);
+extern uint8_t sms_joypad_read(void);
+extern void sms_sprite_init(void);
+extern void sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
+extern void sms_sat_upload(void);
+
+#define MAX_BULLETS 4
+#define MAX_ENEMIES 4
+
+#define T_SHIP   0
+#define T_BULLET 1
+#define T_ENEMY  2
+
+static const uint8_t palette[32] = {
+  0x10,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* Sprite palette: white, yellow, red */
+  0x00,0x3F,0x0F,0x03, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+};
+
+static const uint8_t sprite_tiles[32 * 3] = {
+  /* T_SHIP — diamond using colour 1 (white) */
+  0x18,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+  0x7E,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0x7E,0x00,0x00,0x00,
+  0x3C,0x00,0x00,0x00, 0x18,0x00,0x00,0x00,
+  /* T_BULLET — small ball using colour 2 (yellow → plane 1) */
+  0x00,0x18,0x00,0x00, 0x00,0x3C,0x00,0x00,
+  0x00,0x3C,0x00,0x00, 0x00,0x3C,0x00,0x00,
+  0x00,0x3C,0x00,0x00, 0x00,0x3C,0x00,0x00,
+  0x00,0x18,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* T_ENEMY — X using colour 3 (red → planes 0+1) */
+  0x81,0x81,0x00,0x00, 0x42,0x42,0x00,0x00,
+  0x24,0x24,0x00,0x00, 0x18,0x18,0x00,0x00,
+  0x18,0x18,0x00,0x00, 0x24,0x24,0x00,0x00,
+  0x42,0x42,0x00,0x00, 0x81,0x81,0x00,0x00,
+};
+
+typedef struct { uint8_t x, y, alive; } Obj;
+
+static Obj player;
+static Obj bullets[MAX_BULLETS];
+static Obj enemies[MAX_ENEMIES];
+static uint16_t score;
+static uint8_t spawn_timer;
+
+static uint8_t aabb(Obj *a, Obj *b) {
+  return a->x < b->x + 8 && a->x + 8 > b->x
+      && a->y < b->y + 8 && a->y + 8 > b->y;
+}
+
+static void fire(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_BULLETS; i++) {
+    if (!bullets[i].alive) {
+      bullets[i].x = player.x;
+      bullets[i].y = (uint8_t)(player.y - 8);
+      bullets[i].alive = 1;
+      return;
+    }
+  }
+}
+
+static void spawn(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_ENEMIES; i++) {
+    if (!enemies[i].alive) {
+      enemies[i].x = (uint8_t)(((spawn_timer * 37) & 0xFF) % (256 - 16) + 8);
+      enemies[i].y = 0;
+      enemies[i].alive = 1;
+      return;
+    }
+  }
+}
+
+void main(void) {
+  uint8_t prev = 0;
+
+  sms_vdp_init();
+  sms_load_palette(palette);
+  sms_load_tiles(0x2000, sprite_tiles, 32 * 3);
+
+  player.x = 120; player.y = 160; player.alive = 1;
+  {
+    uint8_t i;
+    for (i = 0; i < MAX_BULLETS; i++) bullets[i].alive = 0;
+    for (i = 0; i < MAX_ENEMIES; i++) enemies[i].alive = 0;
+  }
+  score = 0;
+  spawn_timer = 0;
+
+  sms_sprite_init();
+  sfx_init();
+  sms_vdp_display_on();
+
+  do {
+    uint8_t pad;
+    uint8_t i, j;
+    sms_vblank_wait();
+    sfx_update();
+
+    /* Stage SAT for the new frame. */
+    sms_sprite_set(0, player.x, player.y, T_SHIP);
+    for (i = 0; i < MAX_BULLETS; i++) {
+      uint8_t by = bullets[i].alive ? bullets[i].y : 0xE0; /* off-screen */
+      sms_sprite_set((uint8_t)(1 + i), bullets[i].x, by, T_BULLET);
+    }
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      uint8_t ey = enemies[i].alive ? enemies[i].y : 0xE0;
+      sms_sprite_set((uint8_t)(5 + i), enemies[i].x, ey, T_ENEMY);
+    }
+    sms_sat_upload();
+
+    pad = sms_joypad_read();
+    if (pad & JOY_LEFT  && player.x > 4)        player.x = (uint8_t)(player.x - 2);
+    if (pad & JOY_RIGHT && player.x < 256 - 16) player.x = (uint8_t)(player.x + 2);
+    if (pad & JOY_UP    && player.y > 8)        player.y = (uint8_t)(player.y - 2);
+    if (pad & JOY_DOWN  && player.y < 192 - 16) player.y = (uint8_t)(player.y + 2);
+    if ((pad & JOY_B1) && !(prev & JOY_B1)) { fire(); sfx_tone(0, 200, 4); }
+    prev = pad;
+
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (!bullets[i].alive) continue;
+      if (bullets[i].y < 4) { bullets[i].alive = 0; continue; }
+      bullets[i].y = (uint8_t)(bullets[i].y - 4);
+    }
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      if (!enemies[i].alive) continue;
+      enemies[i].y = (uint8_t)(enemies[i].y + 1);
+      if (enemies[i].y >= 192) enemies[i].alive = 0;
+    }
+    spawn_timer = (uint8_t)(spawn_timer + 1);
+    if (spawn_timer >= 28) { spawn_timer = 0; spawn(); }
+
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (!bullets[i].alive) continue;
+      for (j = 0; j < MAX_ENEMIES; j++) {
+        if (!enemies[j].alive) continue;
+        if (aabb(&bullets[i], &enemies[j])) {
+          bullets[i].alive = 0;
+          enemies[j].alive = 0;
+          if (score < 65500) score = (uint16_t)(score + 10);
+          sfx_noise(8);
+          break;
+        }
+      }
+    }
+  } while (1);
+}

package/examples/sms/templates/shmup_2p.c

@@ -0,0 +1,219 @@
+/* ── shmup_2p.c — SMS two-player competitive shooter ───────────────
+ *
+ * Two-player co-op-competitive shmup on SMS. Player 1 on PORT_JOY_A,
+ * player 2 on PORT_JOY_B (via sms_joypad_read_p2(), the helper that
+ * reassembles P2's split-across-$DC/$DD bit layout into the same
+ * shape as P1).
+ *
+ * Each player has their own ship + bullet pool + score. Enemies are
+ * shared; first hit wins the points.
+ *
+ * SMS hard limits (8 sprites/scanline, 64 sprites total). Slot layout:
+ *   0     → P1 ship
+ *   1     → P2 ship
+ *   2..5  → P1 bullets
+ *   6..9  → P2 bullets
+ *   10..15 → enemies
+ *   total 16 < 64 — plenty of headroom.
+ */
+#include "sms_hw.h"
+#include "sms_sfx.h"
+#include <stdint.h>
+
+extern void    sms_vdp_init(void);
+extern void    sms_vdp_display_on(void);
+extern void    sms_load_palette(const uint8_t *palette);
+extern void    sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void    sms_vblank_wait(void);
+extern uint8_t sms_joypad_read(void);
+extern uint8_t sms_joypad_read_p2(void);
+extern void    sms_sprite_init(void);
+extern void    sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
+extern void    sms_sat_upload(void);
+
+#define MAX_BULLETS_PP 4
+#define MAX_ENEMIES    6
+
+#define T_SHIP_P1 0
+#define T_SHIP_P2 1
+#define T_BULLET  2
+#define T_ENEMY   3
+
+static const uint8_t palette[32] = {
+  0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  /* Sprite palette: 1 white (P1), 2 yellow (bullet), 3 red (enemy + P2 highlight) */
+  0x00, 0x3F, 0x0F, 0x03, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+};
+
+/* 4 sprite tiles back-to-back: P1 ship (col1), P2 ship (col3), bullet (col2), enemy (col3). */
+static const uint8_t sprite_tiles[32 * 4] = {
+  /* P1 ship — diamond, colour 1 (plane 0) */
+  0x18,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+  0x7E,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0x7E,0x00,0x00,0x00,
+  0x3C,0x00,0x00,0x00, 0x18,0x00,0x00,0x00,
+  /* P2 ship — diamond, colour 3 (planes 0+1) */
+  0x18,0x18,0x00,0x00, 0x3C,0x3C,0x00,0x00,
+  0x7E,0x7E,0x00,0x00, 0xFF,0xFF,0x00,0x00,
+  0xFF,0xFF,0x00,0x00, 0x7E,0x7E,0x00,0x00,
+  0x3C,0x3C,0x00,0x00, 0x18,0x18,0x00,0x00,
+  /* Bullet — small ball, colour 2 (plane 1) */
+  0x00,0x18,0x00,0x00, 0x00,0x3C,0x00,0x00,
+  0x00,0x3C,0x00,0x00, 0x00,0x3C,0x00,0x00,
+  0x00,0x3C,0x00,0x00, 0x00,0x3C,0x00,0x00,
+  0x00,0x18,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* Enemy — X, colour 3 (planes 0+1) */
+  0x81,0x81,0x00,0x00, 0x42,0x42,0x00,0x00,
+  0x24,0x24,0x00,0x00, 0x18,0x18,0x00,0x00,
+  0x18,0x18,0x00,0x00, 0x24,0x24,0x00,0x00,
+  0x42,0x42,0x00,0x00, 0x81,0x81,0x00,0x00,
+};
+
+typedef struct { uint8_t x, y, alive; } Obj;
+static Obj p1, p2;
+static Obj p1_bullets[MAX_BULLETS_PP];
+static Obj p2_bullets[MAX_BULLETS_PP];
+static Obj enemies[MAX_ENEMIES];
+static uint16_t score_p1, score_p2;
+static uint8_t spawn_timer;
+
+static uint8_t aabb(Obj *a, Obj *b) {
+  return a->x < b->x + 8 && a->x + 8 > b->x
+      && a->y < b->y + 8 && a->y + 8 > b->y;
+}
+
+static void fire(Obj *ship, Obj *pool) {
+  uint8_t i;
+  for (i = 0; i < MAX_BULLETS_PP; i++) {
+    if (!pool[i].alive) {
+      pool[i].x = ship->x;
+      pool[i].y = (uint8_t)(ship->y - 8);
+      pool[i].alive = 1;
+      return;
+    }
+  }
+}
+
+static void spawn(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_ENEMIES; i++) {
+    if (!enemies[i].alive) {
+      enemies[i].x = (uint8_t)(((spawn_timer * 37) & 0xFF) % (256 - 16) + 8);
+      enemies[i].y = 0;
+      enemies[i].alive = 1;
+      return;
+    }
+  }
+}
+
+void main(void) {
+  uint8_t prev1 = 0, prev2 = 0;
+  sms_vdp_init();
+  sms_load_palette(palette);
+  sms_load_tiles(0x2000, sprite_tiles, 32 * 4);
+
+  p1.x = 80;  p1.y = 160; p1.alive = 1;
+  p2.x = 168; p2.y = 160; p2.alive = 1;
+  {
+    uint8_t i;
+    for (i = 0; i < MAX_BULLETS_PP; i++) p1_bullets[i].alive = 0;
+    for (i = 0; i < MAX_BULLETS_PP; i++) p2_bullets[i].alive = 0;
+    for (i = 0; i < MAX_ENEMIES; i++) enemies[i].alive = 0;
+  }
+  score_p1 = 0; score_p2 = 0; spawn_timer = 0;
+
+  sms_sprite_init();
+  sfx_init();
+  sms_vdp_display_on();
+
+  do {
+    uint8_t pad1, pad2;
+    uint8_t i, j;
+    sms_vblank_wait();
+    sfx_update();
+
+    /* Stage SAT first. */
+    sms_sprite_set(0, p1.x, p1.y, T_SHIP_P1);
+    sms_sprite_set(1, p2.x, p2.y, T_SHIP_P2);
+    for (i = 0; i < MAX_BULLETS_PP; i++) {
+      uint8_t by = p1_bullets[i].alive ? p1_bullets[i].y : 0xE0;
+      sms_sprite_set((uint8_t)(2 + i), p1_bullets[i].x, by, T_BULLET);
+    }
+    for (i = 0; i < MAX_BULLETS_PP; i++) {
+      uint8_t by = p2_bullets[i].alive ? p2_bullets[i].y : 0xE0;
+      sms_sprite_set((uint8_t)(6 + i), p2_bullets[i].x, by, T_BULLET);
+    }
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      uint8_t ey = enemies[i].alive ? enemies[i].y : 0xE0;
+      sms_sprite_set((uint8_t)(10 + i), enemies[i].x, ey, T_ENEMY);
+    }
+    sms_sat_upload();
+
+    pad1 = sms_joypad_read();
+    pad2 = sms_joypad_read_p2();
+
+    /* P1. */
+    if (pad1 & JOY_LEFT  && p1.x > 4)        p1.x = (uint8_t)(p1.x - 2);
+    if (pad1 & JOY_RIGHT && p1.x < 256 - 16) p1.x = (uint8_t)(p1.x + 2);
+    if (pad1 & JOY_UP    && p1.y > 8)        p1.y = (uint8_t)(p1.y - 2);
+    if (pad1 & JOY_DOWN  && p1.y < 192 - 16) p1.y = (uint8_t)(p1.y + 2);
+    if ((pad1 & JOY_B1) && !(prev1 & JOY_B1)) { fire(&p1, p1_bullets); sfx_tone(0, 200, 4); }
+    prev1 = pad1;
+
+    /* P2. */
+    if (pad2 & JOY_LEFT  && p2.x > 4)        p2.x = (uint8_t)(p2.x - 2);
+    if (pad2 & JOY_RIGHT && p2.x < 256 - 16) p2.x = (uint8_t)(p2.x + 2);
+    if (pad2 & JOY_UP    && p2.y > 8)        p2.y = (uint8_t)(p2.y - 2);
+    if (pad2 & JOY_DOWN  && p2.y < 192 - 16) p2.y = (uint8_t)(p2.y + 2);
+    if ((pad2 & JOY_B1) && !(prev2 & JOY_B1)) { fire(&p2, p2_bullets); sfx_tone(1, 250, 4); }
+    prev2 = pad2;
+
+    /* Update bullets. */
+    for (i = 0; i < MAX_BULLETS_PP; i++) {
+      if (p1_bullets[i].alive) {
+        if (p1_bullets[i].y < 4) p1_bullets[i].alive = 0;
+        else p1_bullets[i].y = (uint8_t)(p1_bullets[i].y - 4);
+      }
+      if (p2_bullets[i].alive) {
+        if (p2_bullets[i].y < 4) p2_bullets[i].alive = 0;
+        else p2_bullets[i].y = (uint8_t)(p2_bullets[i].y - 4);
+      }
+    }
+
+    /* Update enemies. */
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      if (!enemies[i].alive) continue;
+      enemies[i].y = (uint8_t)(enemies[i].y + 1);
+      if (enemies[i].y >= 192) enemies[i].alive = 0;
+    }
+    spawn_timer = (uint8_t)(spawn_timer + 1);
+    if (spawn_timer >= 28) { spawn_timer = 0; spawn(); }
+
+    /* Collisions — P1 bullets first, then P2 (gameplay-symmetric tie-break
+     * by player order; for true symmetry, alternate the order each frame). */
+    for (j = 0; j < MAX_ENEMIES; j++) {
+      if (!enemies[j].alive) continue;
+      for (i = 0; i < MAX_BULLETS_PP; i++) {
+        if (p1_bullets[i].alive && aabb(&p1_bullets[i], &enemies[j])) {
+          p1_bullets[i].alive = 0;
+          enemies[j].alive = 0;
+          if (score_p1 < 65500) score_p1 = (uint16_t)(score_p1 + 10);
+          sfx_noise(8);
+          break;
+        }
+      }
+      if (!enemies[j].alive) continue;
+      for (i = 0; i < MAX_BULLETS_PP; i++) {
+        if (p2_bullets[i].alive && aabb(&p2_bullets[i], &enemies[j])) {
+          p2_bullets[i].alive = 0;
+          enemies[j].alive = 0;
+          if (score_p2 < 65500) score_p2 = (uint16_t)(score_p2 + 10);
+          sfx_noise(8);
+          break;
+        }
+      }
+    }
+  } while (1);
+}

package/examples/sms/templates/sports.c

@@ -0,0 +1,147 @@
+/* ── sports.c — SMS two-player Pong scaffold ────────────────────────
+ *
+ * Two-player Pong on the SMS. Both controller ports are wired:
+ *   Player 1 (PORT_JOY_A low 6 bits) — UP/DOWN moves left paddle
+ *   Player 2 (PORT_JOY_A high 2 bits + PORT_JOY_B low 4 bits) — UP/DOWN
+ *     moves right paddle. SMS splits P2 awkwardly across two ports;
+ *     sms_joypad_read_p2() reassembles into the same bit layout as P1.
+ *
+ * When no P2 controller is plugged in, the right paddle falls back to
+ * "chase the ball" AI so the game is still playable solo.
+ *
+ * Designed for the romdev playtest window — plug in a second pad
+ * mid-session and player 2 starts working without a restart.
+ */
+#include "sms_hw.h"
+#include "sms_sfx.h"
+#include <stdint.h>
+
+extern void    sms_vdp_init(void);
+extern void    sms_vdp_display_on(void);
+extern void    sms_load_palette(const uint8_t *palette);
+extern void    sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void    sms_vblank_wait(void);
+extern uint8_t sms_joypad_read(void);
+extern uint8_t sms_joypad_read_p2(void);
+extern void    sms_sprite_init(void);
+extern void    sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
+extern void    sms_sat_upload(void);
+
+#define COURT_TOP   8
+#define COURT_BOT   184
+#define PADDLE_H    24
+#define BALL_SIZE   8
+#define PADDLE_X1   16
+#define PADDLE_X2   232
+
+static const uint8_t palette[32] = {
+  0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  /* Sprite palette: white at idx 1 */
+  0x00, 0x3F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+};
+
+static const uint8_t tile_solid[32] = {
+  0xFF, 0x00, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00,
+  0xFF, 0x00, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00,
+  0xFF, 0x00, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00,
+  0xFF, 0x00, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00,
+};
+
+static int16_t p1y, p2y, bx, by;
+static int8_t  bdx, bdy;
+static uint8_t score_p1, score_p2;
+static uint8_t serve_timer;
+
+static void serve_ball(uint8_t to_left) {
+  bx = 124;
+  by = 90;
+  bdx = to_left ? -2 : 2;
+  bdy = ((score_p1 + score_p2) & 1) ? -1 : 1;
+  serve_timer = 30;
+}
+
+static void reset_match(void) {
+  p1y = 84; p2y = 84;
+  score_p1 = 0; score_p2 = 0;
+  serve_ball(0);
+}
+
+void main(void) {
+  uint8_t i;
+  sms_vdp_init();
+  sms_load_palette(palette);
+  sms_load_tiles(0x2000, tile_solid, 32);
+  sms_sprite_init();
+  sfx_init();
+  sms_vdp_display_on();
+
+  reset_match();
+
+  do {
+    uint8_t p1, p2;
+    uint8_t slot;
+    sms_vblank_wait();
+    sfx_update();
+
+    /* Stage SAT first — uploaded at vblank. */
+    slot = 0;
+    /* Left paddle = 3 stacked 8×8 sprites */
+    for (i = 0; i < PADDLE_H / 8; i++)
+      sms_sprite_set(slot++, PADDLE_X1, (uint8_t)(p1y + i * 8), 0);
+    /* Right paddle */
+    for (i = 0; i < PADDLE_H / 8; i++)
+      sms_sprite_set(slot++, PADDLE_X2, (uint8_t)(p2y + i * 8), 0);
+    /* Ball */
+    sms_sprite_set(slot++, (uint8_t)bx, (uint8_t)by, 0);
+    sms_sat_upload();
+
+    p1 = sms_joypad_read();
+    p2 = sms_joypad_read_p2();
+
+    if ((p1 & JOY_UP)   && p1y > COURT_TOP)            p1y -= 2;
+    if ((p1 & JOY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 2;
+
+    /* P2 input if any, otherwise AI. */
+    if (p2 != 0) {
+      if ((p2 & JOY_UP)   && p2y > COURT_TOP)            p2y -= 2;
+      if ((p2 & JOY_DOWN) && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+    } else {
+      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;
+    }
+
+    if (serve_timer > 0) {
+      serve_timer--;
+    } else {
+      bx = (int16_t)(bx + bdx);
+      by = (int16_t)(by + bdy);
+      if (by < COURT_TOP) { by = COURT_TOP; bdy = (int8_t)(-bdy); sfx_tone(1, 300, 2); }
+      if (by + BALL_SIZE > COURT_BOT) { by = COURT_BOT - BALL_SIZE; bdy = (int8_t)(-bdy); sfx_tone(1, 300, 2); }
+
+      if (bdx < 0
+          && bx <= PADDLE_X1 + 8
+          && bx + BALL_SIZE >= PADDLE_X1
+          && by + BALL_SIZE > p1y
+          && by < p1y + PADDLE_H) {
+        bdx = (int8_t)(-bdx);
+        bx = PADDLE_X1 + 8;
+        sfx_tone(0, 250, 3);
+      }
+      if (bdx > 0
+          && bx + BALL_SIZE >= PADDLE_X2
+          && bx <= PADDLE_X2 + 8
+          && by + BALL_SIZE > p2y
+          && by < p2y + PADDLE_H) {
+        bdx = (int8_t)(-bdx);
+        bx = PADDLE_X2 - BALL_SIZE;
+        sfx_tone(0, 250, 3);
+      }
+
+      if (bx < 4)   { if (score_p2 < 9) score_p2++; sfx_noise(20); serve_ball(0); }
+      if (bx > 252) { if (score_p1 < 9) score_p1++; sfx_tone(0, 180, 16); serve_ball(1); }
+    }
+  } while (1);
+}

package/examples/sms/templates/tile_engine.c

@@ -0,0 +1,137 @@
+/* ── tile_engine.c — SMS tile-map starter ───────────────────────────
+ *
+ * 32×24 tile world drawn on the SMS BG plane with a walking player
+ * sprite + AABB collision against solid tile indices.
+ *
+ * SMS BG name table is at VRAM $3800 — 32 cells wide × 28 rows × 2
+ * bytes per cell. Only 24 rows are visible in mode 4. Each name-table
+ * entry packs: tile_index (10 bits across two bytes) + h/v flip +
+ * palette + priority.
+ */
+#include "sms_hw.h"
+#include "sms_sfx.h"
+#include <stdint.h>
+
+extern void sms_vdp_init(void);
+extern void sms_vdp_display_on(void);
+extern void sms_vdp_write_reg(uint8_t reg, uint8_t value);
+extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
+extern void sms_load_palette(const uint8_t *palette);
+extern void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
+extern void sms_vblank_wait(void);
+extern uint8_t sms_joypad_read(void);
+extern void sms_sprite_init(void);
+extern void sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
+extern void sms_sat_upload(void);
+
+#define WORLD_W 32
+#define WORLD_H 24
+
+#define T_OPEN  0
+#define T_WALL  1
+#define T_SPR   0   /* sprite tile uses sprite-tile-bank (R6=0xFB) */
+
+static const uint8_t palette[32] = {
+  /* BG palette: backdrop blue, wall colour 1 dark grey, colour 2 light grey */
+  0x10,0x14,0x2A,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* Sprite palette: white at idx 1 */
+  0x00,0x3F,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+};
+
+static const uint8_t bg_tiles[32 * 2] = {
+  /* T_OPEN — blank */
+  0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0,
+  0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0,
+  /* T_WALL — bordered block */
+  0xFF,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
+  0x81,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
+  0x81,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
+  0x81,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+};
+
+static const uint8_t sprite_tile[32] = {
+  0x3C,0x00,0x00,0x00, 0x7E,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0x7E,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+};
+
+static uint8_t world[WORLD_H][WORLD_W];
+
+static void world_build(void) {
+  uint8_t y, x;
+  for (y = 0; y < WORLD_H; y++) {
+    for (x = 0; x < WORLD_W; x++) {
+      world[y][x] = (x == 0 || x == WORLD_W - 1
+                     || y == 0 || y == WORLD_H - 1) ? T_WALL : T_OPEN;
+    }
+  }
+  /* A few interior platforms. */
+  for (x = 4; x < 12; x++) world[10][x] = T_WALL;
+  for (x = 16; x < 24; x++) world[14][x] = T_WALL;
+  for (x = 6; x < 10; x++)  world[6][x]  = T_WALL;
+}
+
+static void world_draw(void) {
+  uint8_t y, x;
+  for (y = 0; y < WORLD_H; y++) {
+    for (x = 0; x < WORLD_W; x++) {
+      sms_set_tilemap_cell(y, x, world[y][x], 0);
+    }
+  }
+}
+
+static uint8_t solid_at(int16_t px, int16_t py) {
+  int16_t tx = px >> 3;
+  int16_t ty = py >> 3;
+  if (tx < 0 || tx >= WORLD_W || ty < 0 || ty >= WORLD_H) return 1;
+  return world[ty][tx] != T_OPEN;
+}
+
+void main(void) {
+  int16_t px = 16, py = 16;
+
+  sms_vdp_init();
+  sms_load_palette(palette);
+  /* BG tiles at VRAM $0000 (R4 = 0xFF). Two tiles = 64 bytes. */
+  sms_load_tiles(0x0000, bg_tiles, 64);
+  /* Sprite tile at VRAM $2000. */
+  sms_load_tiles(0x2000, sprite_tile, 32);
+
+  world_build();
+  world_draw();
+
+  sms_sprite_init();
+  sfx_init();
+  sfx_tone(0, 220, 12);
+  sms_sprite_set(0, (uint8_t)px, (uint8_t)py, 0);
+  sms_sat_upload();
+
+  sms_vdp_display_on();
+
+  do {
+    uint8_t pad;
+    int16_t nx, ny;
+    sms_vblank_wait();
+    sfx_update();
+    sms_sprite_set(0, (uint8_t)px, (uint8_t)py, 0);
+    sms_sat_upload();
+
+    pad = sms_joypad_read();
+    nx = px; ny = py;
+    if (pad & JOY_LEFT)  nx = (int16_t)(px - 1);
+    if (pad & JOY_RIGHT) nx = (int16_t)(px + 1);
+    if (pad & JOY_UP)    ny = (int16_t)(py - 1);
+    if (pad & JOY_DOWN)  ny = (int16_t)(py + 1);
+
+    if (!solid_at(nx, py) && !solid_at(nx + 7, py)
+        && !solid_at(nx, py + 7) && !solid_at(nx + 7, py + 7))
+      px = nx;
+    if (!solid_at(px, ny) && !solid_at(px + 7, ny)
+        && !solid_at(px, ny + 7) && !solid_at(px + 7, ny + 7))
+      py = ny;
+  } while (1);
+}