romdevtools 0.16.0 → 0.22.0

package/examples/gb/templates/racing.c

@@ -4,7 +4,12 @@
  * 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 background: grass shoulders down each side, dark
+ * asphalt across the playfield, and dashed white lane lines between the
+ * lanes (LCDC bit 0 = BG ON — drop it and the screen is a flat colour,
+ * the #1 GB "why is it blank" footgun). Cars are sprites on top.
  */
 
 #include "gb_hardware.h"
@@ -16,7 +21,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 +31,41 @@ static const uint8_t tile_car_en[16] = {
   0x00,0x7E, 0x00,0x42, 0x00,0x7E, 0x00,0x66,
 };
 
+/* ── BG tiles (road) ──────────────────────────────────────────────── */
+/* 2bpp: row N = byte 2N (low plane) + byte 2N+1 (high plane).
+ *   asphalt  — all colour 2 (mid-dark)
+ *   grass    — all colour 1 (light, the shoulders)
+ *   laneA/B  — dashed white (colour 3) lane line, two phases for the 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,
+};
+
+/* OBJ palette: 0 transparent, 1 white (player), 2 red, 3 green. */
 static const uint16_t obj_palette[4] = { 0x7FFF, 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;
 
 static Car player;
@@ -71,8 +109,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) {
@@ -83,18 +140,26 @@ 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);
 
+  /* DMG BG palette: 0 white, 1 light, 2 dark, 3 black. The road reads
+   * as asphalt(dark) + grass(light) + white dashes. */
+  BGP = 0xE4;
   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();
@@ -105,13 +170,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/gb/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 scrolling-looking 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 colour 0 (dark) + colour 1, so even an
+ *                empty patch of space mixes two palette shades and never
+ *                lets one colour dominate the frame.
+ *   tile_star  — a bright colour-3 "+" 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,
@@ -82,8 +100,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) {
@@ -97,6 +127,12 @@ 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);
+
+    /* DMG BG palette: 0 dark, 1 mid-dark, 2 light, 3 white — the dithered
+     * space tile mixes shades 0+1 (deep space), stars use shade 3 (white). */
+    BGP = 0xE4;
 
     OCPS = 0x80;
     for (i = 0; i < 4; i++) {
@@ -104,6 +140,8 @@ void main(void) {
         OCPD = (uint8_t)((obj_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;
@@ -111,7 +149,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/gb/templates/sports.c

@@ -28,6 +28,30 @@ 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 colour 0 + colour 1 (the turf), so even
+ *                 an empty patch mixes two shades and never dominates.
+ *   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 int16_t p1y, p2y, bx, by;
@@ -53,8 +77,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) {
@@ -67,6 +107,13 @@ 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);
+
+  /* DMG BG palette: 0 dark, 1 mid, 2 light, 3 white — the dithered turf
+   * mixes shades 0+1, rails/net use shade 2. */
+  BGP = 0xE4;
 
   OCPS = 0x80;
   for (i = 0; i < 4; i++) {
@@ -74,8 +121,9 @@ void main(void) {
     OCPD = (uint8_t)((obj_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/gb/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/gba/templates/gba_hello.c

@@ -1,8 +1,8 @@
 /* ── 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.
+ * published devkitARM tutorial uses. Mode 3 (240×160 bitmap) framebuffer:
+ * draws a navy sky + green ground + a yellow box you move with the d-pad.
  *
  * Build via romdev:
  *   build({ output: "rom", platform:"gba", language:"c", runtime:"libgba",
@@ -35,7 +35,22 @@
 
 #include <gba.h>
 
+#define SCR_W 240
+#define SCR_H 160
+#define BOX   16          /* movable box size in pixels */
+
+/* Fill a solid rectangle in the Mode-3 framebuffer. */
+static void fill_rect(int x, int y, int w, int h, u16 color) {
+    int yy, xx;
+    for (yy = y; yy < y + h; yy++)
+        for (xx = x; xx < x + w; xx++)
+            MODE3_FB[yy][xx] = color;
+}
+
 int main(void) {
+    int x = (SCR_W - BOX) / 2;
+    int y = (SCR_H - BOX) / 2;
+
     /* MODE_3: 240×160 framebuffer, 15-bit color, BG2 = the framebuffer. */
     REG_DISPCNT = MODE_3 | BG2_ON;
 
@@ -43,22 +58,25 @@ int main(void) {
     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++;
+        if ((keys & KEY_LEFT)  && x > 0)            x -= 2;
+        if ((keys & KEY_RIGHT) && x < SCR_W - BOX)  x += 2;
+        if ((keys & KEY_UP)    && y > 0)            y -= 2;
+        if ((keys & KEY_DOWN)  && y < SCR_H - BOX)  y += 2;
 
-        /* Trail effect: don't erase, just keep drawing. */
-        MODE3_FB[y][x] = RGB5(31, 0, 0);
+        /* Draw a recognizable scene every frame:
+         *   - a navy sky filling the whole framebuffer (so it is
+         *     obviously NOT a blank screen),
+         *   - a green ground strip along the bottom,
+         *   - a yellow d-pad-movable box. */
+        fill_rect(0, 0,        SCR_W, SCR_H,      RGB5(2, 4, 12));   /* sky    */
+        fill_rect(0, SCR_H-32, SCR_W, 32,         RGB5(4, 18, 4));   /* ground */
+        fill_rect(x, y,        BOX,   BOX,        RGB5(31, 31, 0));  /* box    */
     }
     return 0;
 }

package/examples/gba/templates/maxmod_demo.c

@@ -47,6 +47,19 @@ extern const u8 soundbank_bin[];
  * Adjust if you regenerate with a differently-named .xm. */
 #define MOD_CHIPTUNE 0
 
+/* ── Backdrop tiles (4bpp) ───────────────────────────────────────────
+ * Two solid-colour tiles so we can lay a two-tone checkerboard across the
+ * whole BG1 map. Without a filled backdrop the screen is just the black
+ * backdrop colour plus a few text glyphs — which reads as "blank". */
+static const u32 tile_solid1[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+static const u32 tile_solid2[8] = {
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+};
+
 int main(void) {
     /* ── IRQ setup ── Maxmod requires mmVBlank() in the VBlank slot.
      * Without this, the mixer DMA buffers never get swapped and audio
@@ -55,9 +68,30 @@ int main(void) {
     irq_init(NULL);
     irq_add(II_VBLANK, mmVBlank);
 
-    /* TTE setup so we can show a status banner. Standard Tonc setup. */
+    /* ── Filled checkerboard backdrop on BG1 ─────────────────────────
+     * Lay a two-tone checkerboard across the whole 32x32 BG1 map so the
+     * frame has real content behind the text instead of a flat black
+     * backdrop (which reads as "blank"). Tiles → char-block 1, map →
+     * screen-block 28 — clear of TTE's char-block 0 / screen-block 31. */
+    pal_bg_mem[0] = CLR_BLACK;
+    pal_bg_mem[1] = RGB15(3, 6, 14);   /* deep sky blue */
+    pal_bg_mem[2] = RGB15(2, 4, 9);    /* darker navy   */
+    tonccpy(&tile_mem[1][1], tile_solid1, sizeof(tile_solid1));
+    tonccpy(&tile_mem[1][2], tile_solid2, sizeof(tile_solid2));
+    REG_BG1CNT = BG_CBB(1) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(3);
+    {
+        SCR_ENTRY *map = se_mem[28];
+        int tx, ty;
+        for (ty = 0; ty < 32; ty++)
+            for (tx = 0; tx < 32; tx++)
+                map[ty * 32 + tx] = SE_BUILD(1 + ((tx ^ ty) & 1), 0, 0, 0);
+    }
+
+    /* TTE setup so we can show a status banner. Standard Tonc setup.
+     * TTE text on BG0 in front of the BG1 backdrop. */
     tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
-    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
+    REG_BG0CNT |= BG_PRIO(0);          /* text in front of the backdrop */
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1;
 
     tte_write("#{P:24,32}");
     tte_write("Maxmod demo");

package/examples/gba/templates/platformer.c

@@ -45,7 +45,9 @@ static const Rect platforms[] = {
     { 440, 120,  56,   8 },
     { 180,  52,  48,   8 },
 };
-#define N_PLATFORMS (sizeof(platforms) / sizeof(platforms[0]))
+/* (int) cast so `for (int i = 0; i < N_PLATFORMS; ...)` doesn't compare a
+ * signed counter against an unsigned size_t (-Wsign-compare). */
+#define N_PLATFORMS ((int)(sizeof(platforms) / sizeof(platforms[0])))
 
 static OBJ_ATTR obj_buffer[128];
 

package/examples/gba/templates/puzzle.c

@@ -60,6 +60,14 @@ static const u32 tile_blue[8] = {
     0x33333333, 0x33333333, 0x33333333, 0x33333333,
     0x33333333, 0x33333333, 0x33333333, 0x33333333,
 };
+/* Backdrop tile (colour index 4 = steel grey): a dither so the whole screen
+ * reads as a "cabinet" behind the playfield instead of flat black — a lone
+ * 6x12 grid floating on black looks blank to a human (frame verify <92%). */
+static const u32 tile_back[8] = {
+    0x40404040, 0x04040404, 0x40404040, 0x04040404,
+    0x40404040, 0x04040404, 0x40404040, 0x04040404,
+};
+#define TILE_BACK 4
 
 static u8 grid[ROWS][COLS];
 
@@ -92,7 +100,7 @@ static int tile_for(u8 cell) {
         case 1: return TILE_RED;
         case 2: return TILE_GREEN;
         case 3: return TILE_BLUE;
-        default: return TILE_BLANK;
+        default: return TILE_BACK;   /* empty cell shows the backdrop, not black */
     }
 }
 
@@ -168,15 +176,19 @@ int main(void) {
     pal_bg_mem[1] = CLR_RED;
     pal_bg_mem[2] = CLR_LIME;
     pal_bg_mem[3] = CLR_BLUE;
+    pal_bg_mem[4] = RGB15(6, 6, 9);   /* steel grey backdrop */
 
     /* BG tile graphics in char-block 3 (separate from TTE which used 2). */
     tonccpy(&tile_mem[3][TILE_RED],   tile_red,   sizeof(tile_red));
     tonccpy(&tile_mem[3][TILE_GREEN], tile_green, sizeof(tile_green));
     tonccpy(&tile_mem[3][TILE_BLUE],  tile_blue,  sizeof(tile_blue));
+    tonccpy(&tile_mem[3][TILE_BACK],  tile_back,  sizeof(tile_back));
 
-    /* Clear screen-block 28 (BG0 map). */
+    /* Fill screen-block 28 (BG0 map) with the backdrop tile so the whole
+     * screen is covered; the grid cells draw over it. (A blank/black map left
+     * the playfield floating on black — reads as blank.) */
     SCR_ENTRY *map = se_mem[28];
-    for (int i = 0; i < 32 * 32; i++) map[i] = SE_BUILD(TILE_BLANK, 0, 0, 0);
+    for (int i = 0; i < 32 * 32; i++) map[i] = SE_BUILD(TILE_BACK, 0, 0, 0);
 
     REG_BG0CNT = BG_CBB(3) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(0);
     /* Bump TTE's BG1 to a LOWER priority so the grid (BG0, prio 0) renders

package/examples/gba/templates/racing.c

@@ -47,6 +47,29 @@ static const u32 tile_car_enemy[8] = {
     0x33333333, 0x34444443, 0x33333333, 0x03300330,
 };
 
+/* ── Road backdrop tiles (4bpp) ──────────────────────────────────────
+ * Fill the whole BG0 with a road scene instead of a flat black screen:
+ *   tile 4 = grass roadside (palette index 5, with darker tufts 6)
+ *   tile 5 = asphalt road   (palette index 7)
+ *   tile 6 = asphalt + a centred white lane dash (index 8)
+ *   tile 7 = road edge line (white index 8 down the left column) */
+static const u32 tile_grass[8] = {
+    0x55555555, 0x55655555, 0x55555555, 0x55556555,
+    0x55555555, 0x65555555, 0x55555555, 0x55555655,
+};
+static const u32 tile_road[8] = {
+    0x77777777, 0x77777777, 0x77777777, 0x77777777,
+    0x77777777, 0x77777777, 0x77777777, 0x77777777,
+};
+static const u32 tile_road_dash[8] = {
+    0x77877877, 0x77877877, 0x77877877, 0x77877877,
+    0x77777777, 0x77777777, 0x77777777, 0x77777777,
+};
+static const u32 tile_road_edge[8] = {
+    0x87777778, 0x87777778, 0x87777778, 0x87777778,
+    0x87777778, 0x87777778, 0x87777778, 0x87777778,
+};
+
 typedef struct { s16 x, y; u16 alive; } Car;
 
 static OBJ_ATTR obj_buffer[128];
@@ -100,6 +123,43 @@ int main(void) {
     tonccpy(&tile_mem[4][TILE_CAR_P1], tile_car_p1,    sizeof(tile_car_p1));
     tonccpy(&tile_mem[4][TILE_CAR_EN], tile_car_enemy, sizeof(tile_car_enemy));
 
+    /* ── Road backdrop on BG0 ────────────────────────────────────────
+     * Paint a full-screen road scene (grass shoulders + asphalt + lane
+     * dashes) so the track doesn't read as a blank black screen. BG
+     * palette: 5 grass / 6 grass-tuft / 7 asphalt / 8 white lines. Tile
+     * data → char-block 0, map → screen-block 28 (clear of TTE on
+     * char-block 2 / screen-block 30). BG0 is lowest priority so the
+     * cars draw in front. The 240-px screen is 30 tiles wide; the road
+     * occupies columns 5..24 with grass on either shoulder. */
+    pal_bg_mem[0]  = CLR_BLACK;
+    pal_bg_mem[5]  = RGB15(4, 16, 5);   /* grass            */
+    pal_bg_mem[6]  = RGB15(2, 11, 3);   /* darker grass tuft*/
+    pal_bg_mem[7]  = RGB15(7, 7, 8);    /* asphalt          */
+    pal_bg_mem[8]  = CLR_WHITE;         /* lane / edge lines*/
+    tonccpy(&tile_mem[0][4], tile_grass,     sizeof(tile_grass));
+    tonccpy(&tile_mem[0][5], tile_road,      sizeof(tile_road));
+    tonccpy(&tile_mem[0][6], tile_road_dash, sizeof(tile_road_dash));
+    tonccpy(&tile_mem[0][7], tile_road_edge, sizeof(tile_road_edge));
+    REG_BG0CNT = BG_CBB(0) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(3);
+    {
+        SCR_ENTRY *map = se_mem[28];
+        for (int ty = 0; ty < 32; ty++) {
+            for (int tx = 0; tx < 32; tx++) {
+                int tile;
+                if (tx < 5 || tx > 24) {
+                    tile = 4;                       /* grass shoulder      */
+                } else if (tx == 5 || tx == 24) {
+                    tile = 7;                       /* white road edge     */
+                } else if ((tx == 11 || tx == 18) && (ty & 1)) {
+                    tile = 6;                       /* dashed lane divider */
+                } else {
+                    tile = 5;                       /* plain asphalt       */
+                }
+                map[ty * 32 + tx] = SE_BUILD(tile, 0, 0, 0);
+            }
+        }
+    }
+
     oam_init(obj_buffer, 128);
 
     /* IRQ setup — required for VBlankIntrWait() to function. */
@@ -108,9 +168,11 @@ int main(void) {
 
     sfx_init();
 
-    /* TTE for score + hint. */
-    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
-    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
+    /* TTE for score + hint on BG1 (BG0 holds the road). char-block 2 /
+     * screen-block 30; priority 0 → text in front of everything. */
+    tte_init_chr4c_default(1, BG_CBB(2) | BG_SBB(30));
+    REG_BG1CNT |= BG_PRIO(0);
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1 | DCNT_OBJ | DCNT_OBJ_1D;
     tte_write("#{P:160,8}SCORE 00000");
     tte_write("#{P:64,150}L/R MOVES LANE");
 

package/examples/gba/templates/shmup.c

@@ -64,6 +64,20 @@ static const u32 tile_enemy[8] = {
     0x33333333, 0x03333330, 0x30000003, 0x03000030,
 };
 
+/* ── Starfield backdrop tiles (4bpp) ─────────────────────────────────
+ * Two space-coloured fill tiles (palette indices 4 and 5) laid in
+ * vertical bands so the whole BG is filled — NOT a flat blank backdrop.
+ * A handful of star pixels (index 6) are punched into each tile so the
+ * field reads as space rather than a solid block. */
+static const u32 tile_star_a[8] = {
+    0x44464444, 0x44444444, 0x46444444, 0x44444644,
+    0x44444444, 0x64444444, 0x44444444, 0x44446444,
+};
+static const u32 tile_star_b[8] = {
+    0x55555555, 0x55655555, 0x55555555, 0x55555565,
+    0x65555555, 0x55555555, 0x55556555, 0x55555555,
+};
+
 typedef struct { s16 x, y; u16 alive; } Obj;
 
 static OBJ_ATTR obj_buffer[128];
@@ -114,6 +128,27 @@ int main(void) {
     pal_obj_bank[1][2] = CLR_YELLOW;  /* bullets */
     pal_obj_bank[2][3] = CLR_RED;     /* enemies */
 
+    /* ── Starfield backdrop on BG0 ───────────────────────────────────
+     * Fill the whole screen with a banded space backdrop + scattered
+     * stars so the playfield doesn't read as a blank black screen. BG
+     * palette indices 4/5 = the two space bands, 6 = star colour. Tile
+     * data → char-block 0, map → screen-block 28 (clear of TTE on
+     * char-block 2 / screen-block 30). BG0 sits at the lowest priority
+     * so the ship/bullets/enemies draw in front of it. */
+    pal_bg_mem[0] = CLR_BLACK;
+    pal_bg_mem[4] = RGB15(1, 2, 7);    /* dark space band   */
+    pal_bg_mem[5] = RGB15(2, 3, 10);   /* lighter band      */
+    pal_bg_mem[6] = RGB15(28, 28, 31); /* stars             */
+    tonccpy(&tile_mem[0][4], tile_star_a, sizeof(tile_star_a));
+    tonccpy(&tile_mem[0][5], tile_star_b, sizeof(tile_star_b));
+    REG_BG0CNT = BG_CBB(0) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(3);
+    {
+        SCR_ENTRY *map = se_mem[28];
+        for (int ty = 0; ty < 32; ty++)
+            for (int tx = 0; tx < 32; tx++)
+                map[ty * 32 + tx] = SE_BUILD(4 + ((ty >> 1) & 1), 0, 0, 0);
+    }
+
     oam_init(obj_buffer, 128);
 
     /* IRQ setup — required for VBlankIntrWait() to function. */
@@ -128,10 +163,12 @@ int main(void) {
     score = 0;
     spawn_timer = 0;
 
-    /* TTE on BG0 at screen-block 31, char-block 0. Renders into VRAM
-     * tile map — no libsysbase / iprintf dependency. */
-    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
-    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
+    /* TTE on BG1 at screen-block 30, char-block 2 (BG0 holds the
+     * starfield). Renders into VRAM tile map — no libsysbase / iprintf
+     * dependency. BG1 priority 0 → score/hint text in front. */
+    tte_init_chr4c_default(1, BG_CBB(2) | BG_SBB(30));
+    REG_BG1CNT |= BG_PRIO(0);
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1 | DCNT_OBJ | DCNT_OBJ_1D;
     tte_write("#{P:8,8}SCORE 00000");
     tte_write("#{P:8,144}D-PAD MOVE  A FIRE");