romdev-mcp 0.1.1

package/examples/gb/templates/shmup.c

@@ -0,0 +1,172 @@
+/* ── shmup.c — Game Boy vertical-shooter scaffold ────────────────────
+ *
+ * Mirrors the NES/Genesis/SNES shmup scaffolds for the Game Boy:
+ *   - Player ship at OAM slot 0
+ *   - 4 bullet slots, 4 enemy slots (smaller pools for the Game Boy's
+ *     40-sprite hard cap — total = 9, leaves plenty of headroom)
+ *   - Wave spawner every ~28 frames
+ *   - Linear movement, AABB collision (8×8 vs 8×8)
+ *   - Score rendered to OAM digits would need a font tile blob; we
+ *     keep a running u16 score in WRAM for now — extend with BG-map
+ *     text rendering when you wire a font.
+ *
+ * GB OAM coords are HARDWARE coords: visible Y range is 16..160,
+ * visible X range is 8..168. Y=0 hides the sprite (off-screen).
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+#define MAX_BULLETS 4
+#define MAX_ENEMIES 4
+
+static const uint8_t tile_blank[16] = { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 };
+static const uint8_t tile_ship[16] = {
+    0x18,0x18, 0x3C,0x3C, 0x7E,0x7E, 0xFF,0xFF,
+    0xFF,0xFF, 0x7E,0x7E, 0x3C,0x3C, 0x18,0x18,
+};
+static const uint8_t tile_bullet[16] = {
+    0x00,0x00, 0x18,0x18, 0x3C,0x3C, 0x3C,0x3C,
+    0x3C,0x3C, 0x3C,0x3C, 0x18,0x18, 0x00,0x00,
+};
+static const uint8_t tile_enemy[16] = {
+    0x81,0x81, 0x42,0x42, 0x24,0x24, 0xFF,0xFF,
+    0xFF,0xFF, 0x24,0x24, 0x42,0x42, 0x81,0x81,
+};
+
+static const uint16_t obj_palette[4] = {
+    0x7FFF, /* 0 transparent */
+    0x7FFF, /* 1 white */
+    0x03E0, /* 2 green */
+    0x001F, /* 3 red */
+};
+
+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) {
+    /* Coord conversion: sprites are stored in screen coords here
+     * (px..px+8) NOT hardware coords. We translate to hardware in OAM. */
+    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 = 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 = ((spawn_timer * 37) & 0x7F) % (160 - 16) + 8;
+            enemies[i].y = 0;
+            enemies[i].alive = 1;
+            return;
+        }
+    }
+}
+
+static void upload_tile(uint8_t slot, const uint8_t *src) {
+    uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
+    uint8_t i;
+    for (i = 0; i < 16; i++) dst[i] = src[i];
+}
+
+void main(void) {
+    uint8_t pad, prev = 0;
+    uint8_t i, j;
+
+    lcd_init_default();
+    LCDC = 0;
+
+    upload_tile(0, tile_blank);
+    upload_tile(1, tile_ship);
+    upload_tile(2, tile_bullet);
+    upload_tile(3, tile_enemy);
+
+    OCPS = 0x80;
+    for (i = 0; i < 4; i++) {
+        OCPD = (uint8_t)(obj_palette[i] & 0xFF);
+        OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF);
+    }
+
+    player.x = 76; player.y = 130; player.alive = 1;
+    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;
+
+    oam_clear();
+    LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+    sound_init();
+
+    while (1) {
+        wait_vblank();
+
+        /* Stage OAM for this frame BEFORE we update game state — the
+         * shadow OAM gets DMA'd next vblank. */
+        for (i = 0; i < 40; i++) oam_set(i, 0, 0, 0, 0);
+        oam_set(0, player.y + 16, player.x + 8, 1, 0);
+        for (i = 0; i < MAX_BULLETS; i++) {
+            if (bullets[i].alive)
+                oam_set(1 + i, bullets[i].y + 16, bullets[i].x + 8, 2, 0);
+        }
+        for (i = 0; i < MAX_ENEMIES; i++) {
+            if (enemies[i].alive)
+                oam_set(5 + i, enemies[i].y + 16, enemies[i].x + 8, 3, 0);
+        }
+        oam_dma_flush();
+
+        pad = joypad_read();
+
+        if (pad & PAD_LEFT  && player.x > 0)        player.x -= 2;
+        if (pad & PAD_RIGHT && player.x < 160 - 8)  player.x += 2;
+        if (pad & PAD_UP    && player.y > 0)        player.y -= 2;
+        if (pad & PAD_DOWN  && player.y < 144 - 8)  player.y += 2;
+        if ((pad & PAD_A) && !(prev & PAD_A)) {
+            fire();
+            sound_play_tone(2, 1900, 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 -= 4;
+        }
+        for (i = 0; i < MAX_ENEMIES; i++) {
+            if (!enemies[i].alive) continue;
+            enemies[i].y += 1;
+            if (enemies[i].y >= 144) enemies[i].alive = 0;
+        }
+        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 += 10;
+                    sound_play_noise(6);
+                    break;
+                }
+            }
+        }
+    }
+}

package/examples/gb/templates/sports.c

@@ -0,0 +1,136 @@
+/* ── sports.c — Game Boy Pong scaffold (player-vs-AI) ─────────────────
+ *
+ * The Game Boy hardware has ONE controller port — no native two-player
+ * support without the Link Cable + custom serial code. So "sports" on
+ * GB is single-controller player-vs-AI Pong: left paddle is the human
+ * (UP/DOWN on port 0), right paddle chases the ball.
+ *
+ * Same gameplay shape as the NES / SMS / Genesis 2P versions — just
+ * with the AI permanently driving port 1.
+ *
+ * Game Boy screen is 160×144. Court spans the full visible area.
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+#define COURT_TOP   8
+#define COURT_BOT   136
+#define PADDLE_H    16
+#define BALL_SIZE   8
+#define PADDLE_X1   16
+#define PADDLE_X2   136
+
+static const uint8_t tile_blank[16] = { 0 };
+/* Solid 8×8 block (white on DMG, colour 1 on CGB). */
+static const uint8_t tile_solid[16] = {
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+};
+
+static const uint16_t obj_palette[4] = { 0x7FFF, 0x001F, 0x03E0, 0x7C00 };
+
+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 = 76;
+  by = 68;
+  bdx = to_left ? -2 : 2;
+  bdy = ((score_p1 + score_p2) & 1) ? -1 : 1;
+  serve_timer = 30;
+}
+
+static void reset_match(void) {
+  p1y = 64;
+  p2y = 64;
+  score_p1 = 0;
+  score_p2 = 0;
+  serve_ball(0);
+}
+
+static void upload_tile(uint8_t slot, const uint8_t *src) {
+  uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
+  uint8_t i;
+  for (i = 0; i < 16; i++) dst[i] = src[i];
+}
+
+void main(void) {
+  uint8_t pad;
+  uint8_t i;
+  int16_t target;
+
+  lcd_init_default();
+  LCDC = 0;
+
+  upload_tile(0, tile_blank);
+  upload_tile(1, tile_solid);
+
+  OCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    OCPD = (uint8_t)(obj_palette[i] & 0xFF);
+    OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF);
+  }
+
+  oam_clear();
+  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+  sound_init();
+
+  reset_match();
+
+  while (1) {
+    wait_vblank();
+
+    /* Stage OAM: left paddle (2 stacked), right paddle (2 stacked), ball. */
+    for (i = 0; i < 40; i++) oam_set(i, 0, 0, 0, 0);
+    oam_set(0, (uint8_t)(p1y + 16),         (uint8_t)(PADDLE_X1 + 8), 1, 0);
+    oam_set(1, (uint8_t)(p1y + 16 + 8),     (uint8_t)(PADDLE_X1 + 8), 1, 0);
+    oam_set(2, (uint8_t)(p2y + 16),         (uint8_t)(PADDLE_X2 + 8), 1, 0);
+    oam_set(3, (uint8_t)(p2y + 16 + 8),     (uint8_t)(PADDLE_X2 + 8), 1, 0);
+    oam_set(4, (uint8_t)(by + 16),          (uint8_t)(bx + 8),        1, 0);
+    oam_dma_flush();
+
+    pad = joypad_read();
+    if (pad & PAD_UP    && p1y > COURT_TOP)            p1y -= 2;
+    if (pad & PAD_DOWN  && p1y < COURT_BOT - PADDLE_H) p1y += 2;
+
+    /* Right-paddle AI — chase ball Y. */
+    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); }
+      if (by + BALL_SIZE > COURT_BOT) { by = COURT_BOT - BALL_SIZE; bdy = (int8_t)(-bdy); }
+
+      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;
+        sound_play_tone(2, 1900, 4);
+      }
+      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;
+        sound_play_tone(2, 1900, 4);
+      }
+
+      if (bx < 4)   { if (score_p2 < 9) score_p2++; sound_play_noise(8); serve_ball(0); }
+      if (bx > 156) { if (score_p1 < 9) score_p1++; sound_play_noise(8); serve_ball(1); }
+    }
+  }
+}

package/examples/gb/templates/tile_engine.c

@@ -0,0 +1,280 @@
+/* ── tile_engine.c — GBC starter with a tile map + multiple rooms ──
+ *
+ * Single-screen-per-room layout (Adventure / Zelda-1 / Sokoban shape).
+ *   - 20×18 BG map 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
+ *
+ * Boot order follows the GBC "must-do" sequence from
+ * src/platforms/gbc/TROUBLESHOOTING.md — do not reorder.
+ *
+ * Tile data layout (8×8, 2bpp, 16 bytes per tile):
+ *   tile 0 — blank          (always reserved so OAM Y=0 doesn't glitch)
+ *   tile 1 — floor          (light)
+ *   tile 2 — wall            (dark, solid outline)
+ *   tile 3 — door             (different color)
+ *   tile 4 — player sprite
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+/* ── Tile data ──────────────────────────────────────────────────── */
+/* Each tile is 16 bytes: 8 rows × 2 bytes/row.
+ * For row N, byte 2N has the LOW colour bits, byte 2N+1 has the HIGH.
+ *   colour 0 = 0 bit lo, 0 bit hi  (transparent on sprites)
+ *   colour 1 = 1 bit lo, 0 bit hi
+ *   colour 2 = 0 bit lo, 1 bit hi
+ *   colour 3 = 1 bit lo, 1 bit hi
+ */
+static const uint8_t tiles[5 * 16] = {
+  /* tile 0: blank (all colour 0) */
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+
+  /* tile 1: floor (all colour 1) */
+  0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00,
+  0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00,
+
+  /* tile 2: wall (all colour 3) */
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+
+  /* tile 3: door (colour 2 outline, colour 1 fill) */
+  0xFF, 0xFF, 0x81, 0xFF, 0x81, 0xFF, 0x81, 0xFF,
+  0x81, 0xFF, 0x81, 0xFF, 0x81, 0xFF, 0xFF, 0xFF,
+
+  /* tile 4: player sprite (colour 3 outline, colour 0 fill) */
+  0x3C, 0x3C, 0x42, 0x42, 0x81, 0x81, 0x81, 0x81,
+  0x81, 0x81, 0x81, 0x81, 0x42, 0x42, 0x3C, 0x3C,
+};
+
+/* ── Palettes (BGR555) ──────────────────────────────────────────── */
+/* CGB palette layout: 8 BG palettes × 4 colours × 2 bytes = 64 bytes.
+ * BCPS bit 7 = auto-increment; bits 5..3 = palette; bits 2..1 = colour;
+ * bit 0 = byte select (lo/hi). 0x80 = "palette 0, colour 0, byte 0, auto-increment". */
+static const uint16_t bg_pal[4] = {
+  0x7FFF,  /* 0: white */
+  0x3DEF,  /* 1: pale yellow (floor) */
+  0x4210,  /* 2: dark grey (door outline) */
+  0x0C63,  /* 3: dark grey (wall) */
+};
+
+/* Sprite palette — single 4-colour palette in OBJ palette 0. */
+static const uint16_t obj_pal[4] = {
+  0x7FFF,  /* 0: transparent */
+  0x001F,  /* 1: red */
+  0x03E0,  /* 2: green */
+  0x7C00,  /* 3: blue (player outline) */
+};
+
+/* ── Rooms ──────────────────────────────────────────────────────── */
+/* 20 columns × 18 rows. Tile index per cell.
+ * Edges are walls (tile 2). One door per side leads to the next room. */
+#define COLS 20
+#define ROWS 18
+#define ROOMS 3
+
+static const uint8_t rooms[ROOMS][ROWS * COLS] = {
+  /* Room 0: a corridor — door on right */
+  {
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+  },
+  /* Room 1: open hall — doors left and right */
+  {
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+  },
+  /* Room 2: end room — door on left only */
+  {
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,2,2,2,2,2,1,1,1,1,2,2,2,2,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,2,1,2,2,1,1,1,1,2,2,1,2,2,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,2,2,1,2,2,1,1,1,1,2,2,1,2,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,2,2,2,2,1,1,1,1,2,2,2,2,2,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+  },
+};
+
+/* ── Helpers ────────────────────────────────────────────────────── */
+static void copy_to_vram(uint8_t *dst, const uint8_t *src, uint16_t n) {
+  uint16_t i;
+  for (i = 0; i < n; i++) dst[i] = src[i];
+}
+
+static void load_bg_palette(void) {
+  uint8_t i;
+  BCPS = 0x80;  /* palette 0, colour 0, lo byte, auto-increment */
+  for (i = 0; i < 4; i++) {
+    BCPD = (uint8_t)(bg_pal[i] & 0xFF);
+    BCPD = (uint8_t)((bg_pal[i] >> 8) & 0xFF);
+  }
+}
+
+static void load_obj_palette(void) {
+  uint8_t i;
+  OCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    OCPD = (uint8_t)(obj_pal[i] & 0xFF);
+    OCPD = (uint8_t)((obj_pal[i] >> 8) & 0xFF);
+  }
+}
+
+static void render_room(uint8_t room_idx) {
+  /* Write the 20×18 map into BG map 1 at $9800. The hardware BG map is
+   * 32 tiles wide, so each game row spans 32 bytes in VRAM but we only
+   * use the first 20. */
+  uint16_t i, j;
+  uint8_t *bg_map = (uint8_t *)0x9800;
+  const uint8_t *room = rooms[room_idx];
+  for (j = 0; j < ROWS; j++) {
+    for (i = 0; i < COLS; i++) {
+      bg_map[j * 32 + i] = room[j * COLS + i];
+    }
+  }
+}
+
+/* Returns true if the tile at (tx, ty) in the current room is solid. */
+static uint8_t solid(uint8_t room_idx, uint8_t tx, uint8_t ty) {
+  uint8_t t;
+  if (tx >= COLS || ty >= ROWS) return 1;
+  t = rooms[room_idx][ty * COLS + tx];
+  return (t == 2);  /* tile 2 = wall */
+}
+
+/* Returns true if the tile at (tx, ty) is a door. */
+static uint8_t is_door(uint8_t room_idx, uint8_t tx, uint8_t ty) {
+  uint8_t t;
+  if (tx >= COLS || ty >= ROWS) return 0;
+  t = rooms[room_idx][ty * COLS + tx];
+  return (t == 3);
+}
+
+void main(void) {
+  uint8_t px = 80;        /* player screen X (hardware = +8) */
+  uint8_t py = 72;        /* player screen Y (hardware = +16) */
+  uint8_t current_room = 0;
+  uint8_t pad;
+  uint8_t nx, ny;
+  uint8_t tx, ty;
+
+  /* ── 1. LCD off, safely ────────────────────────────────────────── */
+  lcd_init_default();
+  LCDC = 0;
+
+  /* ── 2. Upload tile data to VRAM slot 0 ($8000) ────────────────── */
+  copy_to_vram((uint8_t *)0x8000, tiles, sizeof(tiles));
+
+  /* ── 3. Palettes ───────────────────────────────────────────────── */
+  load_bg_palette();
+  load_obj_palette();
+
+  /* ── 4. Render starting room ───────────────────────────────────── */
+  render_room(current_room);
+
+  /* ── 5. Build initial OAM ──────────────────────────────────────── */
+  oam_clear();
+  oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+
+  /* ── 6. LCD back on with BG + OBJ ──────────────────────────────── */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+
+  /* ── 7. Game loop ──────────────────────────────────────────────── */
+  for (;;) {
+    wait_vblank();
+    oam_dma_flush();
+    pad = joypad_read();
+
+    /* Tentative new position. */
+    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 centre (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 >= 152) {        /* right edge → next room */
+        if (current_room < ROOMS - 1) {
+          current_room++;
+          px = 4;             /* enter at left side */
+          py = ny;
+          LCDC = 0;
+          render_room(current_room);
+          LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+          oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+          continue;
+        }
+      } else if (nx <= 4) {   /* left edge → previous room */
+        if (current_room > 0) {
+          current_room--;
+          px = 148;            /* enter at right side */
+          py = ny;
+          LCDC = 0;
+          render_room(current_room);
+          LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+          oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+          continue;
+        }
+      }
+    }
+
+    /* Wall collision — block movement. */
+    if (!solid(current_room, tx, ty)) {
+      px = nx;
+      py = ny;
+    }
+
+    oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+  }
+}

package/examples/gba/templates/gba_hello.c

@@ -0,0 +1,64 @@
+/* ── gba_hello.c — Game Boy Advance libgba starter ──────────────────
+ *
+ * Idiomatic GBA C against the devkitPro libgba SDK — same shape every
+ * published devkitARM tutorial uses. Mode 3 framebuffer, draws a red
+ * pixel that moves left/right via the d-pad.
+ *
+ * Build via romdev:
+ *   buildSource({platform:"gba", language:"c", runtime:"libgba",
+ *                source: <this file>})
+ *
+ * NOTE: the DEFAULT GBA runtime is libtonc (use `tonc_hello.c` instead
+ * for the Tonc-tutorial-aligned starter). This file is the libgba
+ * opt-in path — pass `runtime: "libgba"` to use it.
+ *
+ * The bundled libgba runtime gives you:
+ *   - <gba.h>     umbrella header — pulls in every other libgba header
+ *   - REG_DISPCNT, MODE_3, BG2_ON, etc.   display registers + flags
+ *   - MODE3_FB[]                          framebuffer at 0x06000000
+ *   - RGB5(r,g,b)                         pack a 15-bit color
+ *   - SPRITE_GFX / OAM / BG_PALETTE       sprite + BG memory regions
+ *   - REG_KEYINPUT, KEY_A/B/L/R/SELECT/START etc.   input
+ *   - dmaCopy, dmaFill                    BIOS DMA helpers
+ *   - irqInit, irqEnable                  interrupt table setup
+ *   - VBlankIntrWait()                    frame heartbeat (REQUIRES irq)
+ *
+ * ⚠️  IRQ INIT IS REQUIRED. VBlankIntrWait() is a BIOS function that
+ *    halts the CPU until a vblank IRQ fires. Without irqInit() +
+ *    irqEnable(IRQ_VBLANK) the BIOS halts forever — ROM appears to
+ *    load but freezes on frame 1. Single most common GBA gotcha.
+ *
+ * ⚠️  iprintf-style stdio (console.c) is NOT bundled — see
+ *    TROUBLESHOOTING.md for workarounds. The libtonc default runtime
+ *    provides TTE which sidesteps the issue entirely.
+ */
+
+#include <gba.h>
+
+int main(void) {
+    /* MODE_3: 240×160 framebuffer, 15-bit color, BG2 = the framebuffer. */
+    REG_DISPCNT = MODE_3 | BG2_ON;
+
+    /* IRQ table — REQUIRED for VBlankIntrWait() to function. */
+    irqInit();
+    irqEnable(IRQ_VBLANK);
+
+    int x = 120;
+    int y = 80;
+
+    while (1) {
+        VBlankIntrWait();
+
+        /* Read d-pad. REG_KEYINPUT is active-LOW (bit clear = pressed).
+         * Invert + mask to get "is pressed" semantics. */
+        u16 keys = ~REG_KEYINPUT & 0x3FF;
+        if ((keys & KEY_LEFT)  && x > 0)   x--;
+        if ((keys & KEY_RIGHT) && x < 239) x++;
+        if ((keys & KEY_UP)    && y > 0)   y--;
+        if ((keys & KEY_DOWN)  && y < 159) y++;
+
+        /* Trail effect: don't erase, just keep drawing. */
+        MODE3_FB[y][x] = RGB5(31, 0, 0);
+    }
+    return 0;
+}