romdevtools 0.15.0 → 0.21.0

package/examples/gbc/templates/default.c

@@ -1,19 +1,23 @@
 /* ── default.c — minimal Game Boy Color (CGB) starter ─────────────
  *
- * Boots the LCD, cycles a real CGB background palette via the BCPS
- * + BCPD palette-RAM registers. Smallest possible "ROM that does
- * something visible IN COLOR" — use this as the starting point when
- * you want CGB-mode color, not DMG greyscale.
+ * A "hello, it works! IN COLOR" screen: a tiled background (two bands
+ * + a centre box) drawn with a real CGB palette, plus a sprite that
+ * bounces around. The very first GBC build shows recognizable content
+ * — not a flat colour. Use this as the starting point when you're not
+ * yet sure what you want to build; edit from here.
  *
  * GBC-specific notes:
  *   - CGB uses BCPS/BCPD ($FF68/$FF69) to write into 64 bytes of
- *     palette RAM (8 BG palettes × 4 colors × 2 bytes each, BGR555
- *     little-endian). DMG-only BGP ($FF47) does nothing in CGB mode.
+ *     palette RAM (8 BG palettes × 4 colours × 2 bytes each, BGR555
+ *     little-endian) and OCPS/OCPD for the sprite palettes. The DMG-only
+ *     BGP/OBP0/OBP1 ($FF47-$49) registers do nothing in CGB mode.
+ *   - You MUST put tiles in VRAM and enable the BG (LCDC bit 0) or the
+ *     screen stays one flat colour — the #1 GB "why is it blank" footgun.
+ *     We upload tiles to $8000 and select LCDC_TILE_DATA_LO (unsigned
+ *     $8000 addressing) so tile index N lives at $8000 + N*16.
  *   - patchGbHeader on a .gbc file sets $0143 = $80 (CGB-aware) by
- *     default. The corresponding `.gb` default uses BGP — don't
+ *     default. The corresponding `.gb` default uses DMG BGP — don't
  *     cross-pollinate the two trees.
- *   - This template is intentionally DIFFERENT from examples/gb/
- *     templates/default.c — that one demonstrates DMG palettes.
  *
  * For something more game-shaped, peek at other templates in this dir:
  *   - hello_sprite — sprite + d-pad movement
@@ -25,37 +29,110 @@
 #include "gb_hardware.h"
 #include "gb_runtime.h"
 
-static const uint16_t palettes[4] = {
-  0x7FFF,  /* white */
-  0x3DEF,  /* light grey */
-  0x2108,  /* dark grey */
-  0x0000,  /* black */
+/* Three 8×8 tiles, 2bpp (16 bytes each: row N = byte 2N low-bits, 2N+1
+ * high-bits).  Colour index per tile pixel selects into the 4-colour
+ * palette below.
+ *   tile 0 — blank   (all colour 0 — reserved so OAM Y=0 doesn't glitch)
+ *   tile 1 — solid   (all colour 1 — the background fill / bands)
+ *   tile 2 — sprite  (a filled diamond in colour 3) */
+static const uint8_t tiles[3 * 16] = {
+  /* tile 0: blank */
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* tile 1: solid colour 1 (low plane all-on, high plane all-off) */
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  /* tile 2: diamond in colour 3 (both planes set on the diamond pixels) */
+  0x18,0x18, 0x3C,0x3C, 0x7E,0x7E, 0xFF,0xFF,
+  0xFF,0xFF, 0x7E,0x7E, 0x3C,0x3C, 0x18,0x18,
 };
 
+/* BG palette 0 (BGR555). Colour 0 = backdrop, colour 1 = the bands/box.
+ * We cycle colour 1 through these four shades each ~32 frames so you can
+ * SEE the CGB palette path is alive. */
+static const uint16_t bg_fill_cycle[4] = {
+  0x03FF,  /* yellow-ish */
+  0x7C00,  /* blue       */
+  0x03E0,  /* green      */
+  0x001F,  /* red        */
+};
+
+/* Sprite palette (OBJ palette 0): 0 transparent, 3 = white diamond. */
+static const uint16_t obj_pal[4] = {
+  0x0000,  /* 0 transparent (sprite colour 0 never drawn) */
+  0x7FFF,  /* 1 white  */
+  0x03E0,  /* 2 green  */
+  0x7FFF,  /* 3 white  */
+};
+
+static void set_bg_color1(uint16_t bgr555) {
+  /* Write BG palette 0: colour 0 = dark backdrop, colour 1 = bgr555. */
+  BCPS = 0x80;                              /* palette 0, colour 0, auto-inc */
+  BCPD = 0x08; BCPD = 0x21;                 /* colour 0 = dark grey (0x2108) */
+  BCPD = (uint8_t)(bgr555 & 0xFF);          /* colour 1 lo */
+  BCPD = (uint8_t)((bgr555 >> 8) & 0xFF);   /* colour 1 hi */
+}
+
 void main(void) {
-  uint8_t i;
+  uint8_t x, y;
+  uint8_t sx = 76, sy = 64;        /* sprite screen position */
+  int8_t  dx = 1,  dy = 1;          /* sprite velocity */
   uint8_t shade = 0;
   uint16_t frame = 0;
+  uint8_t *bg_map = BG_MAP_0;       /* $9800 */
+  uint8_t i;
 
+  /* 1. LCD off (safely — lcd_init_default checks LCDC.7 first). */
   lcd_init_default();
+  LCDC = 0;
 
-  /* Initial BG palette = all 4 entries cycle to the same shade. */
-  BCPS = 0x80;
+  /* 2. Tiles → VRAM at $8000 (unsigned addressing, see LCDC_TILE_DATA_LO). */
+  memcpy_vram((void *)0x8000, tiles, sizeof(tiles));
+
+  /* 3. Palettes. */
+  set_bg_color1(bg_fill_cycle[0]);
+  OCPS = 0x80;
   for (i = 0; i < 4; i++) {
-    BCPD = (uint8_t)(palettes[shade] & 0xFF);
-    BCPD = (uint8_t)((palettes[shade] >> 8) & 0xFF);
+    OCPD = (uint8_t)(obj_pal[i] & 0xFF);
+    OCPD = (uint8_t)((obj_pal[i] >> 8) & 0xFF);
+  }
+
+  /* 4. Paint the BG map (32×32; we fill the visible 20×18). Background
+   *    is tile 0 (blank → backdrop colour); two solid bands + a centre
+   *    box are tile 1 so the screen reads as real content. */
+  for (y = 0; y < 32; y++)
+    for (x = 0; x < 32; x++)
+      bg_map[y * 32 + x] = 0;
+  for (x = 0; x < 20; x++) {
+    bg_map[2 * 32 + x]  = 1;   /* top band    (row 2)  */
+    bg_map[15 * 32 + x] = 1;   /* bottom band (row 15) */
   }
+  for (y = 6; y < 12; y++)
+    for (x = 6; x < 14; x++)
+      bg_map[y * 32 + x] = 1;  /* centre box */
+
+  /* 5. Initial sprite. */
+  oam_clear();
+  oam_set(0, (uint8_t)(sy + 16), (uint8_t)(sx + 8), 2, 0);
+
+  /* 6. LCD on with BG + OBJ + $8000 tile addressing. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
 
   for (;;) {
     wait_vblank();
+    oam_dma_flush();
+
     frame++;
-    if ((frame & 0x1F) == 0) {       /* every 32 frames */
-      shade = (shade + 1) & 0x03;
-      BCPS = 0x80;
-      for (i = 0; i < 4; i++) {
-        BCPD = (uint8_t)(palettes[shade] & 0xFF);
-        BCPD = (uint8_t)((palettes[shade] >> 8) & 0xFF);
-      }
+    if ((frame & 0x1F) == 0) {            /* every 32 frames: cycle BG colour */
+      shade = (uint8_t)((shade + 1) & 0x03);
+      set_bg_color1(bg_fill_cycle[shade]);
     }
+
+    /* Bounce the sprite around the 160×144 visible area. */
+    sx = (uint8_t)(sx + dx);
+    sy = (uint8_t)(sy + dy);
+    if (sx < 1 || sx > 152) dx = (int8_t)-dx;
+    if (sy < 1 || sy > 136) dy = (int8_t)-dy;
+    oam_clear();
+    oam_set(0, (uint8_t)(sy + 16), (uint8_t)(sx + 8), 2, 0);
   }
 }

package/examples/gbc/templates/platformer.c

@@ -28,9 +28,26 @@ static const uint8_t tile_platform[16] = {
     0xFF,0xFF, 0x80,0x80, 0x80,0x80, 0x80,0x80,
     0x80,0x80, 0x80,0x80, 0x80,0x80, 0xFF,0xFF,
 };
+/* ── Backdrop tiles ───────────────────────────────────────────────────
+ * Fill the whole world so the screen is never one flat colour (the #1 GB
+ * "why is it blank" footgun). tile_sky is a sparse dot pattern over the
+ * sky; tile_ground is a textured dirt fill under the floor line. */
+static const uint8_t tile_sky[16] = {
+    0x00,0x00, 0x00,0x00, 0x00,0x00, 0x20,0x20,
+    0x00,0x00, 0x00,0x00, 0x02,0x02, 0x00,0x00,
+};
+static const uint8_t tile_ground[16] = {
+    0xFF,0x00, 0xDB,0x24, 0xFF,0x00, 0x6D,0x92,
+    0xFF,0x00, 0xDB,0x24, 0xFF,0x00, 0x6D,0x92,
+};
+#define T_BLANK    0
+#define T_PLATFORM 2
+#define T_SKY      3
+#define T_GROUND   4
 
 static const uint16_t obj_palette[4] = { 0x7FFF, 0x001F, 0x03E0, 0x7C00 };
-static const uint16_t bg_palette[4]  = { 0x7FFF, 0x5294, 0x294A, 0x0000 };
+/* BG palette: 0 sky-blue, 1 mid, 2 dirt-dark, 3 near-black detail. */
+static const uint16_t bg_palette[4]  = { 0x7E10, 0x5294, 0x114A, 0x0000 };
 
 typedef struct { int16_t x, y, w, h; } Rect;
 
@@ -74,8 +91,10 @@ static void paint_platforms(void) {
     const Rect *p;
     /* k MUST be uint16_t: 32*18 = 576 > 255, so a uint8_t counter would
      * never reach the bound and this loop would spin forever (the BG map
-     * never clears, main() never starts). Classic SDCC limited-range trap. */
-    for (k = 0; k < 32 * 18; k++) map[k] = 0; /* blank tile slot 0 */
+     * never clears, main() never starts). Classic SDCC limited-range trap.
+     * Fill sky above the floor line (row 16 = y 128) and textured ground
+     * at and below it, so the whole world is a real scene, not blank. */
+    for (k = 0; k < 32 * 18; k++) map[k] = (k >= 16 * 32) ? T_GROUND : T_SKY;
     for (i = 0; i < N_PLATFORMS; i++) {
         p = &platforms[i];
         cx = p->x >> 3;
@@ -84,7 +103,7 @@ static void paint_platforms(void) {
         ch = (p->h + 7) >> 3;
         for (j = 0; j < cw; j++) {
             if (cx + j < 32 && cy < 32)
-                map[cy * 32 + cx + j] = 2; /* tile slot 2 = platform */
+                map[cy * 32 + cx + j] = T_PLATFORM; /* platform top edge */
         }
     }
 }
@@ -111,6 +130,8 @@ void main(void) {
     upload_tile(0, tile_blank);
     upload_tile(1, tile_player);
     upload_tile(2, tile_platform);
+    upload_tile(T_SKY,    tile_sky);
+    upload_tile(T_GROUND, tile_ground);
 
     OCPS = 0x80;
     for (i = 0; i < 4; i++) {

package/examples/gbc/templates/puzzle.c

@@ -21,8 +21,22 @@
 #define T_R     1
 #define T_G     2
 #define T_B     3
-
-static const uint8_t tile_blank[16] = { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 };
+#define T_WALL  4
+
+/* tile_blank is the EMPTY-cell / backdrop tile. It is NOT all-zero: a
+ * subtle dither (colour 0 + faint colour 1) so the empty playfield and the
+ * area around the well read as a textured surface, never one flat colour
+ * (the #1 GB "why is it blank" footgun). Locked blocks / the active piece
+ * overdraw it with the R/G/B shape tiles. */
+static const uint8_t tile_blank[16] = {
+    0x00,0x00, 0x22,0x00, 0x00,0x00, 0x88,0x00,
+    0x00,0x00, 0x22,0x00, 0x00,0x00, 0x88,0x00,
+};
+/* Well frame: a solid colour-2 border drawn around the play area. */
+static const uint8_t tile_wall[16] = {
+    0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+    0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+};
 /* Three distinct tile shapes (since GB BG is 2bpp, we differentiate
  * by *shape*, not colour-on-CGB). The CGB palette path could give us
  * real colours; for DMG-compatibility we use shape. */
@@ -131,6 +145,20 @@ static void upload_tile(uint8_t slot, const uint8_t *src) {
     for (i = 0; i < 16; i++) dst[i] = src[i];
 }
 
+/* Draw the well frame around the 6×12 play area. Grid cells live at
+ * map[(row+1)*32 + (col+7)] (rows 1..12, cols 7..12), so the frame is the
+ * column to each side (6 and 13) and the floor row just below (row 13). */
+static void draw_well(void) {
+    uint8_t *map = (uint8_t *)0x9800;
+    uint8_t r;
+    for (r = 1; r <= 12; r++) {
+        map[r * 32 + 6]  = T_WALL;   /* left wall  */
+        map[r * 32 + 13] = T_WALL;   /* right wall */
+    }
+    for (r = 6; r <= 13; r++)
+        map[13 * 32 + r] = T_WALL;   /* floor      */
+}
+
 void main(void) {
     uint8_t pad, prev = 0, fall_rate, t;
     int16_t r, c;
@@ -145,6 +173,7 @@ void main(void) {
     upload_tile(T_R,     tile_r);
     upload_tile(T_G,     tile_g);
     upload_tile(T_B,     tile_b);
+    upload_tile(T_WALL,  tile_wall);
 
     BCPS = 0x80;
     for (i = 0; i < 4; i++) {
@@ -165,6 +194,7 @@ void main(void) {
     score = 0;
     fall_timer = 0;
     new_piece();
+    draw_well();
     draw_grid();
 
     LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_TILE_DATA_LO;

package/examples/gbc/templates/racing.c

@@ -1,10 +1,17 @@
-/* ── racing.c — Game Boy top-down racing scaffold ──────────────────
+/* ── racing.c — Game Boy Color top-down racing scaffold ────────────
  *
- * Endless 3-lane top-down dodge for the Game Boy. LEFT/RIGHT switches
- * lanes (edge-detected), obstacles slide down at speed = 2 + score/500
- * (capped). Collision triggers a 60-frame freeze + auto-reset.
+ * Endless 3-lane top-down dodge for the Game Boy Color. LEFT/RIGHT
+ * switches lanes (edge-detected), obstacles slide down at speed =
+ * 2 + score/500 (capped). Collision triggers a 60-frame freeze +
+ * auto-reset.
  *
- * Game Boy screen is 160×144 — 3 lanes centred around x = {48, 80, 112}.
+ * Game Boy screen is 160×144 — 3 lanes centred around x = {40, 76, 112}.
+ *
+ * The road is a real CGB-coloured background: green grass shoulders down
+ * each side, grey asphalt across the playfield, dashed white lane lines
+ * between the lanes (BG palette via BCPS/BCPD; LCDC bit 0 = BG ON — drop
+ * it and the screen is a flat colour, the #1 GB "why is it blank"
+ * footgun). Cars are colour sprites (OCPS/OCPD) on top.
  */
 
 #include "gb_hardware.h"
@@ -16,7 +23,7 @@
 #define PLAYER_Y      120
 #define MAX_OBSTACLES   4
 
-static const uint8_t tile_blank[16] = { 0 };
+/* ── Sprite tiles (cars) ──────────────────────────────────────────── */
 static const uint8_t tile_car_p1[16] = {
   0x3C,0x00, 0x7E,0x00, 0x42,0x00, 0x7E,0x00,
   0x7E,0x00, 0x42,0x00, 0x7E,0x00, 0x66,0x00,
@@ -26,8 +33,43 @@ static const uint8_t tile_car_en[16] = {
   0x00,0x7E, 0x00,0x42, 0x00,0x7E, 0x00,0x66,
 };
 
-static const uint16_t obj_palette[4] = { 0x7FFF, 0x7FFF, 0x001F, 0x03E0 };
-static const uint16_t bg_palette[4]  = { 0x1842, 0x2945, 0x4A53, 0x7FFF };  /* asphalt → lane lines */
+/* ── BG tiles (road) ──────────────────────────────────────────────── */
+/* 2bpp: row N = byte 2N (low plane) + byte 2N+1 (high plane).
+ *   asphalt  — all colour 2 (grey)
+ *   grass    — all colour 1 (green)
+ *   laneA/B  — dashed colour-3 (white) lane line, two phases for dashes */
+static const uint8_t tile_asphalt[16] = {
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+};
+static const uint8_t tile_grass[16] = {
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+};
+/* lane line = a 2px-wide colour-3 stripe down the centre of the cell;
+ * phase A draws the top half, phase B the bottom half → dashes. */
+static const uint8_t tile_laneA[16] = {
+  0x18,0x18, 0x18,0x18, 0x18,0x18, 0x18,0x18,
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+};
+static const uint8_t tile_laneB[16] = {
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+  0x18,0x18, 0x18,0x18, 0x18,0x18, 0x18,0x18,
+};
+
+/* CGB palettes (BGR555).
+ * BG palette 0: 0 unused, 1 green grass, 2 grey asphalt, 3 white line. */
+static const uint16_t bg_palette[4]  = { 0x0000, 0x0320, 0x4210, 0x7FFF };
+/* OBJ palette 0: 0 transparent, 1 white (player), 2 red (enemy), 3 green. */
+static const uint16_t obj_palette[4] = { 0x0000, 0x7FFF, 0x001F, 0x03E0 };
+
+/* Tile indices in VRAM. Sprites and BG share the $8000 table here. */
+#define T_CAR_P1   1
+#define T_CAR_EN   2
+#define T_ASPHALT  3
+#define T_GRASS    4
+#define T_LANE_A   5
+#define T_LANE_B   6
 
 typedef struct { int16_t x, y; uint8_t alive; } Car;
 
@@ -76,6 +118,24 @@ static void upload_tile(uint8_t slot, const uint8_t *src) {
   for (i = 0; i < 16; i++) dst[i] = src[i];
 }
 
+/* Paint the road into BG map 0 ($9800). 20×18 visible cells:
+ *   col 0       = grass shoulder (left)
+ *   col 19      = grass shoulder (right)
+ *   cols 1..18  = asphalt, with dashed lane lines at the two lane
+ *                 boundaries (cols 6 and 12). Dashes alternate per row. */
+static void draw_road(void) {
+  uint8_t *bg = BG_MAP_0;
+  uint8_t r, c, t;
+  for (r = 0; r < 18; r++) {
+    for (c = 0; c < 20; c++) {
+      if (c == 0 || c == 19)      t = T_GRASS;
+      else if (c == 6 || c == 12) t = (r & 1) ? T_LANE_A : T_LANE_B;
+      else                        t = T_ASPHALT;
+      bg[r * 32 + c] = t;
+    }
+  }
+}
+
 void main(void) {
   uint8_t pad;
   uint8_t i;
@@ -84,23 +144,29 @@ void main(void) {
   lcd_init_default();
   LCDC = 0;
 
-  upload_tile(0, tile_blank);
-  upload_tile(1, tile_car_p1);
-  upload_tile(2, tile_car_en);
+  upload_tile(T_CAR_P1,  tile_car_p1);
+  upload_tile(T_CAR_EN,  tile_car_en);
+  upload_tile(T_ASPHALT, tile_asphalt);
+  upload_tile(T_GRASS,   tile_grass);
+  upload_tile(T_LANE_A,  tile_laneA);
+  upload_tile(T_LANE_B,  tile_laneB);
 
-  OCPS = 0x80;
-  for (i = 0; i < 4; i++) {
-    OCPD = (uint8_t)(obj_palette[i] & 0xFF);
-    OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF);
-  }
+  /* CGB palettes. */
   BCPS = 0x80;
   for (i = 0; i < 4; i++) {
     BCPD = (uint8_t)(bg_palette[i] & 0xFF);
     BCPD = (uint8_t)((bg_palette[i] >> 8) & 0xFF);
   }
+  OCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    OCPD = (uint8_t)(obj_palette[i] & 0xFF);
+    OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF);
+  }
+
+  draw_road();
 
   oam_clear();
-  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
   sound_init();
 
   reset_run();
@@ -111,13 +177,13 @@ void main(void) {
 
     /* Stage OAM — player + obstacles. */
     for (i = 0; i < 40; i++) oam_set(i, 0, 0, 0, 0);
-    oam_set(0, (uint8_t)(player.y + 16), (uint8_t)(player.x + 8), 1, 0);
+    oam_set(0, (uint8_t)(player.y + 16), (uint8_t)(player.x + 8), T_CAR_P1, 0);
     for (i = 0; i < MAX_OBSTACLES; i++) {
       if (obstacles[i].alive) {
         oam_set((uint8_t)(1 + i),
                 (uint8_t)(obstacles[i].y + 16),
                 (uint8_t)(obstacles[i].x + 8),
-                2, 0);
+                T_CAR_EN, 0);
       }
     }
     oam_dma_flush();

package/examples/gbc/templates/shmup.c

@@ -25,6 +25,24 @@ static const uint8_t tile_ship[16] = {
     0x18,0x18, 0x3C,0x3C, 0x7E,0x7E, 0xFF,0xFF,
     0xFF,0xFF, 0x7E,0x7E, 0x3C,0x3C, 0x18,0x18,
 };
+/* ── BG tiles (starfield) ─────────────────────────────────────────────
+ * The background is a real starfield so the screen is never one flat
+ * colour (LCDC_BG_ON below — drop it and the screen reads as blank, the
+ * #1 GB "why is it blank" footgun).
+ *   tile_space — a 50/50 dither of palette colours 0 (deep space blue) +
+ *                1 (mid blue), so even an empty patch of space mixes two
+ *                shades and never lets one colour dominate the frame.
+ *   tile_star  — a bright colour-3 (white) "+" star on the dithered field. */
+static const uint8_t tile_space[16] = {
+    0x55,0x00, 0xAA,0x00, 0x55,0x00, 0xAA,0x00,
+    0x55,0x00, 0xAA,0x00, 0x55,0x00, 0xAA,0x00,
+};
+static const uint8_t tile_star[16] = {
+    0x10,0x10, 0x10,0x10, 0x54,0x54, 0x38,0x38,
+    0x54,0x54, 0x10,0x10, 0x10,0x10, 0x00,0x00,
+};
+#define T_SPACE 4
+#define T_STAR  5
 static const uint8_t tile_bullet[16] = {
     0x00,0x00, 0x18,0x18, 0x3C,0x3C, 0x3C,0x3C,
     0x3C,0x3C, 0x3C,0x3C, 0x18,0x18, 0x00,0x00,
@@ -94,6 +112,17 @@ static void upload_tile(uint8_t slot, const uint8_t *src) {
     for (i = 0; i < 16; i++) dst[i] = src[i];
 }
 
+/* Paint a starfield into BG map 0 ($9800): fill the visible 20×18 with the
+ * dithered space tile, then scatter bright stars on a fixed pseudo-pattern
+ * so the field reads as deep space rather than a flat colour. */
+static void draw_starfield(void) {
+    uint8_t *bg = BG_MAP_0;
+    uint8_t r, c;
+    for (r = 0; r < 18; r++)
+        for (c = 0; c < 20; c++)
+            bg[r * 32 + c] = ((r * 7 + c * 5) % 11 == 0) ? T_STAR : T_SPACE;
+}
+
 void main(void) {
     uint8_t pad, prev = 0;
     uint8_t i, j;
@@ -105,6 +134,8 @@ void main(void) {
     upload_tile(1, tile_ship);
     upload_tile(2, tile_bullet);
     upload_tile(3, tile_enemy);
+    upload_tile(T_SPACE, tile_space);
+    upload_tile(T_STAR,  tile_star);
 
     /* Sprite palette 0 — uploaded to OCPS/OCPD (CGB-only registers). */
     OCPS = 0x80;
@@ -120,6 +151,8 @@ void main(void) {
         BCPD = (uint8_t)((bg_palette[i] >> 8) & 0xFF);
     }
 
+    draw_starfield();
+
     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;
@@ -127,7 +160,7 @@ void main(void) {
     spawn_timer = 0;
 
     oam_clear();
-    LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+    LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
     sound_init();
 
     while (1) {

package/examples/gbc/templates/sports.c

@@ -28,6 +28,31 @@ static const uint8_t tile_solid[16] = {
   0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
 };
 
+/* ── BG tiles (the court) ──────────────────────────────────────────────
+ * A real playfield behind the paddles so the screen is never one flat
+ * colour (LCDC_BG_ON below — drop it and it reads as blank, the #1 GB
+ * "why is it blank" footgun).
+ *   tile_court  — a 50/50 dither of palette colours 0 + 1 (the green turf),
+ *                 so even an empty patch mixes two shades and never
+ *                 dominates the frame.
+ *   tile_net    — a dashed vertical centre-net stripe (colour 2).
+ *   tile_wall   — a solid colour-2 border for the top / bottom rails. */
+static const uint8_t tile_court[16] = {
+  0x55,0x55, 0xAA,0xAA, 0x55,0x55, 0xAA,0xAA,
+  0x55,0x55, 0xAA,0xAA, 0x55,0x55, 0xAA,0xAA,
+};
+static const uint8_t tile_net[16] = {
+  0x18,0x18, 0x18,0x18, 0x00,0x00, 0x00,0x00,
+  0x18,0x18, 0x18,0x18, 0x00,0x00, 0x00,0x00,
+};
+static const uint8_t tile_wall[16] = {
+  0x00,0x00, 0xFF,0xFF, 0xFF,0xFF, 0x00,0x00,
+  0x00,0x00, 0xFF,0xFF, 0xFF,0xFF, 0x00,0x00,
+};
+#define T_COURT 2
+#define T_NET   3
+#define T_WALL  4
+
 static const uint16_t obj_palette[4] = { 0x7FFF, 0x001F, 0x03E0, 0x7C00 };
 static const uint16_t bg_palette[4]  = { 0x2104, 0x294A, 0x4631, 0x7FFF };  /* deep court green */
 
@@ -58,6 +83,21 @@ static void upload_tile(uint8_t slot, const uint8_t *src) {
   for (i = 0; i < 16; i++) dst[i] = src[i];
 }
 
+/* Paint the Pong court into BG map 0 ($9800): dithered turf everywhere,
+ * solid top/bottom rails, and a dashed net down the centre column. */
+static void draw_court(void) {
+  uint8_t *bg = BG_MAP_0;
+  uint8_t r, c, t;
+  for (r = 0; r < 18; r++) {
+    for (c = 0; c < 20; c++) {
+      if (r == 0 || r == 17)      t = T_WALL;          /* top / bottom rail */
+      else if (c == 9 || c == 10) t = (r & 1) ? T_NET : T_COURT; /* net dashes */
+      else                        t = T_COURT;
+      bg[r * 32 + c] = t;
+    }
+  }
+}
+
 void main(void) {
   uint8_t pad;
   uint8_t i;
@@ -68,6 +108,9 @@ void main(void) {
 
   upload_tile(0, tile_blank);
   upload_tile(1, tile_solid);
+  upload_tile(T_COURT, tile_court);
+  upload_tile(T_NET,   tile_net);
+  upload_tile(T_WALL,  tile_wall);
 
   OCPS = 0x80;
   for (i = 0; i < 4; i++) {
@@ -80,8 +123,9 @@ void main(void) {
     BCPD = (uint8_t)((bg_palette[i] >> 8) & 0xFF);
   }
 
+  draw_court();
   oam_clear();
-  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
   sound_init();
 
   reset_match();

package/examples/genesis/templates/puzzle.c

@@ -29,8 +29,23 @@
 #define T_RED   (TILE_USER_INDEX + 1)
 #define T_GREEN (TILE_USER_INDEX + 2)
 #define T_BLUE  (TILE_USER_INDEX + 3)
+#define T_BG    (TILE_USER_INDEX + 4)   /* full-screen backdrop (BG_A) */
+#define T_WELL  (TILE_USER_INDEX + 5)   /* play-well backdrop (BG_A)   */
 
 static const u32 tile_blank[8] = { 0,0,0,0,0,0,0,0 };
+/* Backdrop block for the far plane: a framed cell (colour 4 border /
+ * colour 5 fill) tiled across the whole screen so the playfield no
+ * longer floats on a flat black backdrop. */
+static const u32 tile_bg[8] = {
+    0x44444444, 0x45555554, 0x45555554, 0x45555554,
+    0x45555554, 0x45555554, 0x45555554, 0x44444444,
+};
+/* A darker, recessed cell drawn behind the play column so the well reads
+ * as an inset board rather than part of the surrounding wall. */
+static const u32 tile_well[8] = {
+    0x44444444, 0x40000004, 0x40000004, 0x40000004,
+    0x40000004, 0x40000004, 0x40000004, 0x44444444,
+};
 static const u32 tile_red[8]   = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
@@ -91,8 +106,11 @@ static void draw_cell(s16 col, s16 row) {
     /* Each grid cell is CELL_PX/8 = 2 tiles square. */
     for (u16 dy = 0; dy < 2; dy++) {
         for (u16 dx = 0; dx < 2; dx++) {
+            /* Cells use the EMPTY-or-coloured tile. Empty cells stay
+             * transparent so the BG_A well backdrop shows through; filled
+             * cells are HIGH priority so they sit above that backdrop. */
             VDP_setTileMapXY(BG_B,
-                TILE_ATTR_FULL(pal_for(v), 0, 0, 0, tile_for(v)),
+                TILE_ATTR_FULL(pal_for(v), v ? 1 : 0, 0, 0, tile_for(v)),
                 col * 2 + dx + 6,
                 row * 2 + dy + 1);
         }
@@ -116,7 +134,7 @@ static void draw_piece(s16 col, s16 row, bool clear) {
         for (u16 dy = 0; dy < 2; dy++)
             for (u16 dx = 0; dx < 2; dx++)
                 VDP_setTileMapXY(BG_B,
-                    TILE_ATTR_FULL(pal_for(v), 0, 0, 0, tile_for(v)),
+                    TILE_ATTR_FULL(pal_for(v), v ? 1 : 0, 0, 0, tile_for(v)),
                     col * 2 + dx + 6,
                     r   * 2 + dy + 1);
     }
@@ -166,15 +184,31 @@ static void render_score(void) {
 int main(bool hard) {
     (void)hard;
 
-    /* Palette 1: tile colours for red/green/blue cells. */
+    /* Palette 1: tile colours for red/green/blue cells + the backdrop. */
     PAL_setColor(16 + 1, 0x000E); /* red */
     PAL_setColor(16 + 2, 0x00E0); /* green */
     PAL_setColor(16 + 3, 0x0E00); /* blue */
+    PAL_setColor(16 + 4, 0x0420); /* backdrop wall border */
+    PAL_setColor(16 + 5, 0x0610); /* backdrop wall fill   */
 
     VDP_loadTileData(tile_blank, T_BLANK, 1, DMA);
     VDP_loadTileData(tile_red,   T_RED,   1, DMA);
     VDP_loadTileData(tile_green, T_GREEN, 1, DMA);
     VDP_loadTileData(tile_blue,  T_BLUE,  1, DMA);
+    VDP_loadTileData(tile_bg,    T_BG,    1, DMA);
+    VDP_loadTileData(tile_well,  T_WELL,  1, DMA);
+
+    /* Far plane (BG_A): tile the whole 40x28 screen with the wall block,
+     * then recess the 12x24-cell play column so the grid sits in an inset
+     * well. The grid (BG_B) draws over this with HIGH priority. */
+    for (u16 cy = 0; cy < 28; cy++)
+        for (u16 cx = 0; cx < 40; cx++)
+            VDP_setTileMapXY(BG_A,
+                TILE_ATTR_FULL(PAL1, 0, 0, 0, T_BG), cx, cy);
+    for (u16 cy = 1; cy <= 24; cy++)
+        for (u16 cx = 6; cx <= 17; cx++)
+            VDP_setTileMapXY(BG_A,
+                TILE_ATTR_FULL(PAL1, 0, 0, 0, T_WELL), cx, cy);
 
     for (s16 r = 0; r < ROWS; r++)
         for (s16 c = 0; c < COLS; c++)