romdevtools 0.16.0 → 0.22.0

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;
 
@@ -72,8 +114,27 @@ static void spawn_obstacle(void) {
 
 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];
+  /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+  memcpy_vram(dst, src, 16);
+}
+
+/* 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) {
@@ -84,23 +145,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 +178,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,
@@ -90,8 +108,20 @@ static void spawn(void) {
 
 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];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
+}
+
+/* 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) {
@@ -105,6 +135,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 +152,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 +161,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 */
 
@@ -54,8 +79,24 @@ static void reset_match(void) {
 
 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];
+  /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+  memcpy_vram(dst, src, 16);
+}
+
+/* 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) {
@@ -68,6 +109,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 +124,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/gbc/templates/tile_engine.c

@@ -143,8 +143,9 @@ static const uint8_t rooms[ROOMS][ROWS * COLS] = {
 
 /* ── 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];
+  /* Delegate to the runtime's pointer-walk copy — an indexed dst[i]=src[i]
+   * loop into VRAM is miscompiled by SDCC sm83. */
+  memcpy_vram(dst, src, n);
 }
 
 static void load_bg_palette(void) {

package/examples/genesis/main.s

@@ -89,7 +89,7 @@ Start:
         move.w  #$0000,VDP_DATA      ; color 0: transparent / backdrop
         move.w  #$0EEE,VDP_DATA      ; color 1: white-ish ($0E in each nybble)
         move.w  #$00EE,VDP_DATA      ; color 2: yellow
-        move.w  #$0E00,VDP_DATA      ; color 3: blue (unused)
+        move.w  #$0840,VDP_DATA      ; color 3: dark teal (backdrop fill)
 
         ; -----------------------------------------------------------
         ; Upload one 4bpp tile (8x8 'H', color 2 = yellow) to VRAM at
@@ -104,6 +104,34 @@ Start:
         move.l  (a1)+,VDP_DATA       ; each row = one longword (4 bytes)
         dbra    d0,.tile_loop
 
+        ; -----------------------------------------------------------
+        ; Upload two PATTERNED backdrop tiles (#2 and #3) to VRAM at
+        ; byte offsets $40 and $60 (VRAM cmd $40400000). Each is a teal
+        ; (color 3) field sprinkled with white (color 1) dots, with the
+        ; roles swapped between the two so that when we checkerboard them
+        ; across the plane no single colour dominates the screen — a
+        ; uniform fill still reads as "blank" to a human, so we vary it.
+        ; 16 longwords total (8 rows × 2 tiles) written back-to-back.
+        move.l  #$40400000,VDP_CTRL
+        lea     TileBgA(pc),a1
+        moveq   #16-1,d0             ; 8 rows × 2 tiles
+.bg_tile_loop:
+        move.l  (a1)+,VDP_DATA
+        dbra    d0,.bg_tile_loop
+
+        ; -----------------------------------------------------------
+        ; Fill the ENTIRE plane A name table, checkerboarding tiles #2
+        ; and #3 so there's a varied visible background behind the 'H'.
+        ; Plane A base is $C000; plane size is 64x32 = 2048 cells. VRAM
+        ; write at $C000 = cmd $40000003. d1 toggles 2↔3 each cell.
+        move.l  #$40000003,VDP_CTRL
+        move.w  #2048-1,d0           ; 2048 cells to write
+        moveq   #2,d1               ; start with tile #2
+.bg_fill_loop:
+        move.w  d1,VDP_DATA          ; tile d1 (pal 0, no flip, low pri)
+        eor.w   #$0001,d1            ; toggle 2↔3 (tile index xor 1)
+        dbra    d0,.bg_fill_loop
+
         ; -----------------------------------------------------------
         ; Place tile #1 in plane A near screen center.
         ; Plane A base is at VRAM $C000 (default after VDP init).
@@ -159,3 +187,27 @@ TileH:
         dc.l    $20000020
         dc.l    $20000020
         dc.l    $00000000       ; row 7: blank
+
+; -----------------------------------------------------------------------
+; Two patterned backdrop tiles, 4bpp, uploaded back-to-back as #2 and #3.
+; TileBgA = teal (color 3) field with white (color 1) dots; TileBgB swaps
+; the roles (white field, teal dots). Checkerboarding them across the
+; plane keeps any single colour well under the "blank" threshold.
+TileBgA:                         ; tile #2 — teal field, white dots
+        dc.l    $33333333
+        dc.l    $33133313
+        dc.l    $33333333
+        dc.l    $13333331
+        dc.l    $33333333
+        dc.l    $33133313
+        dc.l    $33333333
+        dc.l    $13333331
+TileBgB:                         ; tile #3 — white field, teal dots
+        dc.l    $11111111
+        dc.l    $11311131
+        dc.l    $11111111
+        dc.l    $31111113
+        dc.l    $11111111
+        dc.l    $11311131
+        dc.l    $11111111
+        dc.l    $31111113

package/examples/genesis/templates/hello_sprite.c

@@ -29,6 +29,17 @@ static const u32 tile_data[8] = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
 };
 
+/* A checkered backdrop block tiled across plane B so the screen isn't a
+ * flat black void (a lone sprite on black reads as "blank" to a human).
+ * Colour index 4 with a thin colour-5 frame — we set both below. */
+static const u32 tile_bg[8] = {
+    0x44444444, 0x45555554, 0x45000054, 0x45000054,
+    0x45000054, 0x45000054, 0x45555554, 0x44444444,
+};
+
+#define T_SPRITE (TILE_USER_INDEX + 0)
+#define T_BG     (TILE_USER_INDEX + 1)
+
 int main(bool hard) {
     (void)hard;
 
@@ -38,11 +49,22 @@ int main(bool hard) {
 
     /* Make sure sprite palette 0 entry 1 is white so we can see our
      * tile. SGDK uses 0RRR0GGG0BBB packed words (BGR, 3 bits each). */
-    PAL_setColor(1, 0x0EEE); /* near-white */
+    PAL_setColor(1, 0x0EEE); /* near-white sprite */
+    /* Plane-B backdrop colours (palette 1). */
+    PAL_setColor(16 + 4, 0x0640); /* dark teal field */
+    PAL_setColor(16 + 5, 0x0860); /* lighter frame   */
 
     /* Upload the user tile to VRAM at TILE_USER_INDEX (everything
      * below that is reserved for SGDK's font + system tiles). */
-    VDP_loadTileData(tile_data, TILE_USER_INDEX, 1, DMA);
+    VDP_loadTileData(tile_data, T_SPRITE, 1, DMA);
+    VDP_loadTileData(tile_bg,   T_BG,     1, DMA);
+
+    /* Tile plane B with the backdrop block so there's a visible
+     * background behind the sprite + text. Sprites + the font plane (A)
+     * always draw above plane B, so the d-pad sprite reads on top. */
+    for (u16 cy = 0; cy < 28; cy++)
+        for (u16 cx = 0; cx < 40; cx++)
+            VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_BG), cx, cy);
 
     VDP_drawText("D-PAD MOVES THE SPRITE", 8, 2);
     VDP_drawText("START FOR SOFT RESET",  9, 4);
@@ -66,7 +88,7 @@ int main(bool hard) {
          * SPRITE_SIZE(1,1) = 8×8. TILE_ATTR_FULL(palette,prio,vflip,
          * hflip,tile_index). */
         VDP_setSprite(0, px, py, SPRITE_SIZE(1, 1),
-                      TILE_ATTR_FULL(PAL0, 0, 0, 0, TILE_USER_INDEX));
+                      TILE_ATTR_FULL(PAL0, 1, 0, 0, T_SPRITE));
         VDP_updateSprites(1, DMA);
 
         SYS_doVBlankProcess();

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++)

package/examples/genesis/templates/racing.c

@@ -29,6 +29,8 @@
 #define T_CAR_EN   (TILE_USER_INDEX + 1)
 #define T_LANE     (TILE_USER_INDEX + 2)   /* dashed lane divider (BG_B) */
 #define T_EDGE     (TILE_USER_INDEX + 3)   /* solid road edge      (BG_B) */
+#define T_GRASS    (TILE_USER_INDEX + 4)   /* roadside backdrop    (BG_A) */
+#define T_ASPHALT  (TILE_USER_INDEX + 5)   /* road surface backdrop(BG_A) */
 
 static const u32 tile_car_p1[8] = {
     0x01111110, 0x11111111, 0x12222221, 0x11111111,
@@ -51,6 +53,18 @@ static const u32 tile_edge[8] = {
     0x00000022, 0x00000022, 0x00000022, 0x00000022,
     0x00000022, 0x00000022, 0x00000022, 0x00000022,
 };
+/* Roadside grass (colour 5) with a couple of darker tufts (colour 6) so
+ * it isn't a flat fill — tiled down both shoulders on BG_A. */
+static const u32 tile_grass[8] = {
+    0x55555555, 0x55556555, 0x55555555, 0x65555555,
+    0x55555555, 0x55555565, 0x55555555, 0x55655555,
+};
+/* Road asphalt (colour 6) with faint speckle (colour 5) — tiled across
+ * the driving surface on BG_A, behind the BG_B lane markings + cars. */
+static const u32 tile_asphalt[8] = {
+    0x66666666, 0x66666566, 0x66666666, 0x56666666,
+    0x66666666, 0x66666656, 0x66666666, 0x66566666,
+};
 
 /* The road lives on BG_B (8×8 cells). Two dashed dividers sit between the
  * three lanes; solid edges frame the outermost lanes. */
@@ -61,15 +75,28 @@ static const u32 tile_edge[8] = {
 #define ROAD_EDGE_L    ((LANE_LEFT_X  - 12) / 8)
 #define ROAD_EDGE_R    ((LANE_RIGHT_X + 12) / 8)
 
+/* Far plane (BG_A): grass shoulders + asphalt driving surface, tiled
+ * across the whole 40x28 screen so the road no longer floats on black.
+ * Drawn at low priority; the BG_B markings + sprite cars sit on top. */
+static void draw_backdrop(void) {
+    s16 r, c;
+    for (r = 0; r < 28; r++)
+        for (c = 0; c < 40; c++) {
+            u16 t = (c >= ROAD_EDGE_L && c <= ROAD_EDGE_R) ? T_ASPHALT : T_GRASS;
+            VDP_setTileMapXY(BG_A, TILE_ATTR_FULL(PAL0, 0, 0, 0, t), c, r);
+        }
+}
+
 static void draw_road(void) {
     s16 r;
     for (r = ROAD_TOP_ROW; r <= ROAD_BOT_ROW; r++) {
-        /* Left edge (stripe on its right), right edge (hflipped). */
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_EDGE), ROAD_EDGE_L, r);
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 1, T_EDGE), ROAD_EDGE_R, r);
+        /* Left edge (stripe on its right), right edge (hflipped). HIGH
+         * priority so the markings sit above the BG_A asphalt backdrop. */
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 0, T_EDGE), ROAD_EDGE_L, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 1, T_EDGE), ROAD_EDGE_R, r);
         /* Two dashed lane dividers. */
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_LANE), LANE_DIV1_COL, r);
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_LANE), LANE_DIV2_COL, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 0, T_LANE), LANE_DIV1_COL, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 0, T_LANE), LANE_DIV2_COL, r);
     }
 }
 
@@ -125,18 +152,24 @@ static void render_score(void) {
 int main(bool hard) {
     (void)hard;
 
-    /* PAL0 = player (white + blue trim). PAL1 = enemy (red + dark). */
+    /* PAL0 = player (white + blue trim) + road backdrop. PAL1 = enemy. */
     PAL_setColor(0 + 1, 0x0EEE);    /* white body */
     PAL_setColor(0 + 2, 0x0AAA);    /* roof grey */
+    PAL_setColor(0 + 5, 0x0260);    /* roadside grass */
+    PAL_setColor(0 + 6, 0x0222);    /* asphalt grey   */
     PAL_setColor(16 + 3, 0x000E);   /* enemy red */
     PAL_setColor(16 + 4, 0x0666);   /* enemy roof */
 
-    VDP_loadTileData(tile_car_p1,    T_CAR_P1, 1, DMA);
-    VDP_loadTileData(tile_car_enemy, T_CAR_EN, 1, DMA);
-    VDP_loadTileData(tile_lane,      T_LANE,   1, DMA);
-    VDP_loadTileData(tile_edge,      T_EDGE,   1, DMA);
+    VDP_loadTileData(tile_car_p1,    T_CAR_P1,  1, DMA);
+    VDP_loadTileData(tile_car_enemy, T_CAR_EN,  1, DMA);
+    VDP_loadTileData(tile_lane,      T_LANE,    1, DMA);
+    VDP_loadTileData(tile_edge,      T_EDGE,    1, DMA);
+    VDP_loadTileData(tile_grass,     T_GRASS,   1, DMA);
+    VDP_loadTileData(tile_asphalt,   T_ASPHALT, 1, DMA);
 
-    /* Draw the static road (edges + dashed lane dividers) once on BG_B. */
+    /* Draw the grass+asphalt backdrop (BG_A) then the road markings on
+     * BG_B over it. */
+    draw_backdrop();
     draw_road();
 
     VDP_drawText("SCORE", 28, 2);

package/examples/genesis/templates/sgdk_hello.c

@@ -21,6 +21,23 @@
 
 #include <genesis.h>
 
+/* Two simple 8x8 background tiles for the far plane (BG_B). Tiling them
+ * in a checkerboard fills the whole screen so it doesn't read as a blank
+ * black backdrop. T_BG_A is a framed block (colour 1 border, colour 2
+ * fill); T_BG_B is the same block in colour 3 — alternating them gives a
+ * two-tone grid with a clear majority of non-backdrop pixels. */
+#define T_BG_A (TILE_USER_INDEX + 0)
+#define T_BG_B (TILE_USER_INDEX + 1)
+
+static const u32 tile_bg_a[8] = {
+    0x11111111, 0x12222221, 0x12222221, 0x12222221,
+    0x12222221, 0x12222221, 0x12222221, 0x11111111,
+};
+static const u32 tile_bg_b[8] = {
+    0x11111111, 0x13333331, 0x13333331, 0x13333331,
+    0x13333331, 0x13333331, 0x13333331, 0x11111111,
+};
+
 int main(bool hard) {
     /* Boot info: hard == TRUE on power-on, FALSE on soft reset (we
      * could re-init differently in each case; this minimum starter
@@ -28,7 +45,23 @@ int main(bool hard) {
     (void)hard;
 
     /* SGDK initialized the VDP + default palette in sega.s + libmd
-     * before main() ran. Just draw text. */
+     * before main() ran. We add a tiled background so the screen isn't a
+     * flat black backdrop, then draw the text on top. */
+    PAL_setColor(16 + 1, 0x0444); /* dark grey grid border */
+    PAL_setColor(16 + 2, 0x0A22); /* deep blue fill        */
+    PAL_setColor(16 + 3, 0x022A); /* deep red fill (2nd block) */
+
+    VDP_loadTileData(tile_bg_a, T_BG_A, 1, DMA);
+    VDP_loadTileData(tile_bg_b, T_BG_B, 1, DMA);
+
+    /* Fill the far plane (BG_B) with a checkerboard of the two blocks so
+     * a clear majority of the visible 40x28 cells are non-backdrop. */
+    for (u16 cy = 0; cy < 28; cy++)
+        for (u16 cx = 0; cx < 40; cx++)
+            VDP_setTileMapXY(BG_B,
+                TILE_ATTR_FULL(PAL1, 0, 0, 0, ((cx ^ cy) & 1) ? T_BG_A : T_BG_B),
+                cx, cy);
+
     VDP_drawText("HELLO SEGA GENESIS", 10, 12);
     VDP_drawText("BUILT WITH ROM-DEV-MCP", 8, 14);