romdevtools 0.16.0 → 0.22.0

package/examples/gba/templates/sports.c

@@ -35,6 +35,22 @@ static const u32 tile_solid_1[8] = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
 };
+/* BG court tiles (4bpp). The court fills BG1 so the arena isn't flat black
+ * (paddles+ball alone on black read as blank to a human — frame verify <92%).
+ *   TILE_COURT (idx1 green): the playing surface, tiled across the screen.
+ *   TILE_NET   (idx2 white): a dashed vertical centre net. */
+#define TILE_COURT 1
+#define TILE_NET   2
+/* Court surface as a two-green checkerboard (idx1 + idx3) so no single colour
+ * dominates the screen — a flat one-colour court still trips the blank check. */
+static const u32 tile_court[8] = {
+    0x11331133, 0x11331133, 0x11331133, 0x11331133,
+    0x33113311, 0x33113311, 0x33113311, 0x33113311,
+};
+static const u32 tile_net[8] = {
+    0x00022000, 0x00022000, 0x00000000, 0x00000000,
+    0x00022000, 0x00022000, 0x00000000, 0x00000000,
+};
 
 static OBJ_ATTR obj_buffer[128];
 
@@ -76,9 +92,27 @@ int main(void) {
 
     sfx_init();
 
-    /* TTE for scores + hint. */
+    /* TTE for scores + hint (BG0). */
     tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
-    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
+
+    /* Court background on BG1 so the arena reads as a real Pong court, not
+     * flat black. Tiles in char-block 1, map in screen-block 29. */
+    pal_bg_mem[1] = RGB15(2, 12, 4);   /* court green (light) */
+    pal_bg_mem[2] = CLR_WHITE;          /* net                */
+    pal_bg_mem[3] = RGB15(1, 8, 3);    /* court green (dark)  */
+    tonccpy(&tile_mem[1][TILE_COURT], tile_court, sizeof(tile_court));
+    tonccpy(&tile_mem[1][TILE_NET],   tile_net,   sizeof(tile_net));
+    {
+        SCR_ENTRY *cmap = se_mem[29];
+        int tx, ty;
+        for (ty = 0; ty < 32; ty++)
+            for (tx = 0; tx < 32; tx++)
+                cmap[ty * 32 + tx] = SE_BUILD(
+                    (tx == 15) ? TILE_NET : TILE_COURT, 0, 0, 0);
+    }
+    REG_BG1CNT = BG_CBB(1) | BG_SBB(29) | BG_REG_32x32 | BG_4BPP | BG_PRIO(3);
+
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1 | DCNT_OBJ | DCNT_OBJ_1D;
     tte_write("#{P:16,2}P1");
     tte_write("#{P:208,2}P2");
     tte_write("#{P:36,150}UP/DOWN MOVES YOUR PADDLE");

package/examples/gba/templates/tonc_hello.c

@@ -31,17 +31,53 @@
 
 #include <tonc.h>
 
+/* ── Backdrop tiles (4bpp, 8 rows × 32 bits) ─────────────────────────
+ * Two solid colour tiles so the whole BG0 map reads as a checkerboard,
+ * not a flat blank backdrop. Every nibble of tile 1 = palette index 1,
+ * every nibble of tile 2 = palette index 2 — so the tile is one solid
+ * colour. (m3_fill's tiled-mode equivalent: paint the whole screen.) */
+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) {
+    /* ── Filled tiled backdrop on BG0 ────────────────────────────
+     * Without this the screen is just the black backdrop colour and a
+     * few text glyphs — which reads as "blank". We lay a two-tone
+     * checkerboard across the entire 32x32 BG0 map so a clear majority
+     * of the screen is coloured (the GBA tiled-mode analogue of
+     * m3_fill-ing a Mode-3 framebuffer). Tile data → char-block 0,
+     * map → screen-block 28 (clear of TTE's char-block 2 / SBB 30). */
+    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[0][1], tile_solid1, sizeof(tile_solid1));
+    tonccpy(&tile_mem[0][2], tile_solid2, sizeof(tile_solid2));
+    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(1 + ((tx ^ ty) & 1), 0, 0, 0);
+    }
+
     /* Initialise TTE in 4-bits-per-pixel chr-mode with the built-in
      * sys8 font. Cleanest API in the entire GBA ecosystem — one call
-     * gets you a usable text terminal on BG0.
+     * gets you a usable text terminal. We put it on BG1 (char-block 2,
+     * screen-block 30) so it sits cleanly in front of the BG0 backdrop.
      *
      * NOTE: we deliberately do NOT call tte_init_con() — that lives
      * in the excluded tte_iohook.c (the libsysbase bridge). Without
      * it, printf/iprintf don't route through TTE — but `tte_write` /
      * `tte_printf` work directly without any libsysbase plumbing,
      * which is what the Tonc tutorial uses everywhere anyway. */
-    tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
+    tte_init_chr4c_default(1, BG_CBB(2) | BG_SBB(30));
+    REG_BG1CNT |= BG_PRIO(0);          /* text in front of the backdrop */
 
     /* ── IRQ setup ── REQUIRED for VBlankIntrWait() to work ──────
      * Without this, the BIOS halts the CPU on the first
@@ -50,9 +86,9 @@ int main(void) {
     irq_init(NULL);
     irq_add(II_VBLANK, NULL);
 
-    /* Set DISPCNT — turn on BG0 (where TTE drew the font tiles into
-     * char-base 0 + screen-base 31). DCNT_MODE0 is the tile-BG mode. */
-    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
+    /* Set DISPCNT — turn on BG0 (the filled backdrop) and BG1 (TTE
+     * text). DCNT_MODE0 is the tile-BG mode. */
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1;
 
     /* Draw text. tte_write moves the internal cursor; \n wraps. */
     tte_write("#{P:32,32}");         /* position cursor at pixel (32,32) */

package/examples/gba/templates/tonc_hello_sprite.c

@@ -35,6 +35,19 @@ static const u32 sprite_tile[8] = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
 };
 
+/* ── Backdrop tiles (4bpp) ───────────────────────────────────────────
+ * Two solid-colour BG tiles so we can lay a two-tone checkerboard across
+ * the whole BG0 map. Without a filled backdrop the screen is just the
+ * black backdrop colour and one tiny sprite — which reads as "blank". */
+static const u32 bg_tile1[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+static const u32 bg_tile2[8] = {
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+};
+
 /* Shadow OAM. Tonc's recommended pattern: allocate your own 128-slot
  * buffer in WRAM, mutate it freely each frame, then oam_copy to push
  * the changes to OAM hardware via DMA. */
@@ -81,12 +94,33 @@ int main(void) {
         ATTR2_PALBANK(0) | 0);
     obj_set_pos(&obj_buffer[0], x, y);
 
+    /* ── Filled checkerboard backdrop on BG0 ─────────────────────
+     * Lay a two-tone checkerboard across the whole 32x32 BG0 map so the
+     * frame has real content behind the sprite instead of a flat black
+     * backdrop (which reads as "blank"). BG tiles → char-block 0, map →
+     * screen-block 28 (the OBJ tiles live in char-block 4, so there's no
+     * clash). */
+    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[0][1], bg_tile1, sizeof(bg_tile1));
+    tonccpy(&tile_mem[0][2], bg_tile2, sizeof(bg_tile2));
+    REG_BG0CNT = BG_CBB(0) | 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);
+    }
+
     /* ── Display setup ───────────────────────────────────────────
      * DCNT_MODE0  — tiled mode (so BG0..3 are tile maps)
+     * DCNT_BG0    — enable the checkerboard backdrop
      * DCNT_OBJ    — enable sprites
      * DCNT_OBJ_1D — linear OAM tile addressing (vs the 2D matrix
      *               layout that's almost always wrong) */
-    REG_DISPCNT = DCNT_MODE0 | DCNT_OBJ | DCNT_OBJ_1D;
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
 
     /* ── Game loop ───────────────────────────────────────────────
      * key_poll() updates the key state — call it once per frame.

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/hello_sprite.c

@@ -54,6 +54,8 @@ void main(void) {
   uint8_t x = 80;       /* hardware X = screen X + 8 */
   uint8_t y = 80;       /* hardware Y = screen Y + 16 */
   uint8_t i;
+  uint8_t *bg_map;
+  uint16_t j;
 
   /* ── 1. LCD off (safe whether it was on or off) ──────────────────
    * lcd_init_default() checks LCDC.7 and only waits for vblank if the
@@ -71,6 +73,13 @@ void main(void) {
    * TROUBLESHOOTING.md "VRAM stays empty / sprite never appears". */
   memcpy_vram((uint8_t *)0x8010, tile_data, 16);
 
+  /* ── 2b. Fill the BG tilemap so the screen isn't an empty backdrop. ──
+   * With LCDC_TILE_DATA_LO ($8000 addressing) BG tile index 1 == our tile
+   * at $8010 — so we tile the whole 32×32 BG map with it. Pointer-walk write
+   * (NOT bg_map[k]=1, which SDCC sm83 miscompiles into VRAM). */
+  bg_map = (uint8_t *)0x9800;
+  for (j = 0; j < 32u * 32u; j++) *bg_map++ = 1;
+
   /* ── 3. Object palette 0 (CGB path) ──────────────────────────────
    * OCPS bit 7 = auto-increment after each write; bits 5..3 = palette
    * index (0..7); bits 2..1 = color index (0..3); bit 0 = MSB select.
@@ -102,9 +111,9 @@ void main(void) {
   oam_dma_flush();
 
   /* ── 5. Turn the LCD back on with BG + OBJ enabled. ──────────────
-   * LCDC bits: 0x80=LCD on, 0x02=OBJ on, 0x10=tile data at $8000.
-   * (BG remains off — we have no BG map set up.) */
-  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+   * LCDC bits: 0x80=LCD on, 0x01=BG on, 0x02=OBJ on, 0x10=tile data at $8000.
+   * BG is on now that we filled the BG map in step 2b. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
 
   /* ── 6. APU on — let the player beep ──────────────────────────── */
   sound_init();

package/examples/gbc/templates/music_demo.c

@@ -23,6 +23,9 @@
 
 extern const huge_song_t sample_song;
 
+/* CGB BG palette 0: backdrop colour cycles (bg_colors[shade]) while
+ * colours 1..3 stay fixed and bright, so the checkerboard backdrop below
+ * always shows several distinct colours (not a single flat field). */
 static const uint16_t bg_colors[4] = {
   0x4210,  /* dim purple */
   0x4308,  /* dim blue   */
@@ -30,21 +33,66 @@ static const uint16_t bg_colors[4] = {
   0x0017,  /* dim red    */
 };
 
+/* Two 8×8 2bpp tiles so the BG isn't a single flat colour:
+ *   tile 1 — solid colour 1
+ *   tile 2 — solid colour 2
+ * Checkerboarded across the BG map below. */
+static const uint8_t tile_solid1[16] = {
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+};
+static const uint8_t tile_solid2[16] = {
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+};
+
+/* Write CGB BG palette 0 with the current backdrop shade plus fixed bright
+ * colours 1..3 (blue / green / white) so the checkerboard is multi-colour. */
+static void set_bg_palette(uint8_t shade) {
+  BCPS = 0x80;            /* auto-increment, start at palette 0 colour 0 */
+  /* colour 0 — animated backdrop */
+  BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
+  BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
+  /* colour 1 — bright blue */
+  BCPD = (uint8_t)(0x7C00u & 0xFFu);
+  BCPD = (uint8_t)((0x7C00u >> 8) & 0xFFu);
+  /* colour 2 — bright green */
+  BCPD = (uint8_t)(0x03E0u & 0xFFu);
+  BCPD = (uint8_t)((0x03E0u >> 8) & 0xFFu);
+  /* colour 3 — white */
+  BCPD = (uint8_t)(0x7FFFu & 0xFFu);
+  BCPD = (uint8_t)((0x7FFFu >> 8) & 0xFFu);
+}
+
 void main(void) {
-  uint8_t  i;
   uint8_t  shade = 0;
   uint16_t frame = 0;
+  uint8_t *bg_map;
+  uint16_t j;
 
   lcd_init_default();
-  sound_init();
+  LCDC = 0;               /* LCD off so we can write VRAM freely */
 
-  /* Write the initial CGB BG palette 0 (4 entries, same colour). */
-  BCPS = 0x80;            /* auto-increment, start at index 0 */
-  for (i = 0; i < 4; i++) {
-    BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
-    BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
+  /* Upload two tiles to VRAM slots 1 ($8010) and 2 ($8020). Use
+   * memcpy_vram (pointer-walk) — an indexed dst[i]=src[i] loop into VRAM
+   * is miscompiled by SDCC sm83. */
+  memcpy_vram((uint8_t *)0x8010, tile_solid1, 16);
+  memcpy_vram((uint8_t *)0x8020, tile_solid2, 16);
+
+  /* Checkerboard the 32×32 BG map at $9800 with tiles 1 and 2. Pointer-walk
+   * (NOT bg_map[k]=..., which SDCC sm83 miscompiles into VRAM). */
+  bg_map = (uint8_t *)0x9800;
+  for (j = 0; j < 32u * 32u; j++) {
+    *bg_map++ = (uint8_t)((((j ^ (j >> 5)) & 1u) ? 1u : 2u));
   }
 
+  set_bg_palette(shade);
+
+  /* LCD on with BG enabled, $8000 tile-data addressing. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_TILE_DATA_LO;
+
+  sound_init();
+
   hUGE_init(&sample_song);
 
   for (;;) {
@@ -53,11 +101,7 @@ void main(void) {
     frame++;
     if ((frame & 0x3F) == 0) {     /* every 64 frames ≈ 1 s */
       shade = (uint8_t)((shade + 1) & 0x03);
-      BCPS = 0x80;
-      for (i = 0; i < 4; i++) {
-        BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
-        BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
-      }
+      set_bg_palette(shade);
     }
   }
 }

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;
 
@@ -61,8 +78,9 @@ static uint8_t on_platform(int16_t px, int16_t py) {
 
 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);
 }
 
 static void paint_platforms(void) {
@@ -74,8 +92,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 +104,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 +131,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. */
@@ -127,8 +141,23 @@ static void lock_piece(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);
+}
+
+/* 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) {
@@ -145,6 +174,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 +195,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;