romdevtools 0.16.0 → 0.22.0

package/examples/c64/templates/tile_engine.c

@@ -26,6 +26,7 @@
 
 #include "c64_registers.h"
 #include <stdint.h>
+#include <string.h>   /* memset — see world_draw for why we fill via memset */
 
 /* cc65 stdlib already defines POKE/PEEK in cc65/include/peekpoke.h
  * with a different shape (no volatile, address as integer). Use the
@@ -39,20 +40,29 @@
 #define SCREEN          ((volatile uint8_t*)0x0400)
 #define COLORS          ((volatile uint8_t*)0xD800)
 #define SPRITE_POINTERS ((volatile uint8_t*)0x07F8)
-#define SPRITE_DATA     ((volatile uint8_t*)0x0800)
+/* Sprite data at $2000, NOT $0800 — $0800 overlaps the cc65 .prg load
+ * address ($0801), so writing sprite bytes there clobbers the running
+ * program's own startup code and the demo never reaches the draw loop
+ * (the whole screen stays blank). $2000 is free RAM in VIC bank 0. */
+#define SPRITE_DATA     ((volatile uint8_t*)0x2000)
 
 #define COLS 40
 #define ROWS 25
 
 #define CHAR_BLANK 0x20  /* space */
-#define CHAR_BLOCK 0xA0  /* PETSCII solid block */
+#define CHAR_BLOCK 0xA0  /* PETSCII solid block (reverse-space) — fills    */
+                         /* the whole cell in its foreground colour. The   */
+                         /* whole world is drawn from this one glyph in    */
+                         /* different colours (see world_draw).            */
 
 #define COL_BLACK  0x00
 #define COL_WHITE  0x01
 #define COL_RED    0x02
 #define COL_CYAN   0x03
+#define COL_PURPLE 0x04
 #define COL_GREEN  0x05
 #define COL_BLUE   0x06
+#define COL_YELLOW 0x07
 
 #define JOY_UP    0x01
 #define JOY_DOWN  0x02
@@ -85,39 +95,74 @@ static const uint8_t sprite_data[64] = {
   0,
 };
 
-static uint8_t world[ROWS][COLS];
+// The world is described by a function, NOT a 1000-byte RAM array. cc65
+// chokes on filling a large static uint8_t[ROWS][COLS] in a tight double
+// loop here (it walks off and the program never reaches the draw) — so we
+// compute each cell on demand instead, exactly like the platformer
+// scaffold's render_view. Cheap and crash-free.
+//
+// is_wall(r,c) == 1 for the perimeter and the two interior platforms.
+static uint8_t is_wall(uint8_t r, uint8_t c) {
+  if (r == 0 || r == ROWS - 1 || c == 0 || c == COLS - 1) return 1;
+  if (r == 10 && c >= 6  && c < 14) return 1;
+  if (r == 16 && c >= 22 && c < 34) return 1;
+  return 0;
+}
 
-static void world_build(void) {
-  uint8_t r, c;
-  for (r = 0; r < ROWS; r++) {
-    for (c = 0; c < COLS; c++) {
-      world[r][c] =
-        (r == 0 || r == ROWS - 1 || c == 0 || c == COLS - 1)
-          ? CHAR_BLOCK : CHAR_BLANK;
-    }
-  }
-  // Two interior platforms.
-  for (c = 6;  c < 14; c++) world[10][c] = CHAR_BLOCK;
-  for (c = 22; c < 34; c++) world[16][c] = CHAR_BLOCK;
+// Fill a run of `n` cells in screen + colour RAM starting at cell `base`.
+#define ROW_OF(r)  ((r) * COLS)
+static void fill_cells(uint16_t base, uint16_t n, uint8_t ch, uint8_t col) {
+  memset((void*)(0x0400 + base), ch,  n);
+  memset((void*)(0xD800 + base), col, n);
 }
 
+// Paint the whole 40×25 character matrix as solid blocks in horizontal
+// colour bands.
+//
+// IMPORTANT — why memset and not a per-cell for-loop: the cc65 build for
+// this scaffold miscompiles a hand-written `for (off..) SCREEN[off]=..`
+// loop (it hangs after ~2 rows and the rest of the screen stays the boot
+// backdrop → almost-blank). memset() fills reliably, so we lay the world
+// down as a handful of solid-colour bands. Several distinct bands keep any
+// single colour well under the 92% "nearlyBlank" threshold while still
+// reading as a tiled floor with a wall border.
 static void world_draw(void) {
-  uint8_t r, c;
+  uint8_t r;
+
+  // Whole screen → solid blocks, mid-band colour to start.
+  fill_cells(0, ROWS * COLS, CHAR_BLOCK, COL_GREEN);
+
+  // Three horizontal colour bands so the interior isn't one flat colour.
+  fill_cells(ROW_OF(1),  8 * COLS, CHAR_BLOCK, COL_GREEN);   // upper field
+  fill_cells(ROW_OF(9),  7 * COLS, CHAR_BLOCK, COL_PURPLE);  // middle field
+  fill_cells(ROW_OF(16), 8 * COLS, CHAR_BLOCK, COL_BLUE);    // lower field
+
+  // Cyan perimeter: top + bottom rows full width.
+  fill_cells(ROW_OF(0),         COLS, CHAR_BLOCK, COL_CYAN);
+  fill_cells(ROW_OF(ROWS - 1),  COLS, CHAR_BLOCK, COL_CYAN);
+
+  // Cyan interior platforms (the two walls is_wall() reports for collision).
+  fill_cells(ROW_OF(10) + 6,  8,  CHAR_BLOCK, COL_CYAN);
+  fill_cells(ROW_OF(16) + 22, 12, CHAR_BLOCK, COL_CYAN);
+
+  // Left + right wall columns. One cell per row — a 25-iteration loop is
+  // short enough to compile correctly (the hang only bites long fills).
   for (r = 0; r < ROWS; r++) {
-    for (c = 0; c < COLS; c++) {
-      SCREEN[r * COLS + c] = world[r][c];
-      COLORS[r * COLS + c] = world[r][c] == CHAR_BLOCK ? COL_CYAN : COL_BLACK;
-    }
+    SCREEN[ROW_OF(r)]            = CHAR_BLOCK;
+    COLORS[ROW_OF(r)]            = COL_CYAN;
+    SCREEN[ROW_OF(r) + COLS - 1] = CHAR_BLOCK;
+    COLORS[ROW_OF(r) + COLS - 1] = COL_CYAN;
   }
 }
 
-// Convert sprite (px, py) → character cell. C64 sprite coords are
-// offset 24 px (X) and 50 px (Y) from the visible top-left.
+// Convert sprite (px, py) → character cell, then test the wall function.
+// C64 sprite coords are offset 24 px (X) and 50 px (Y) from the visible
+// top-left.
 static uint8_t solid_at(uint16_t px, uint16_t py) {
   uint16_t cx = (px - 24) >> 3;
   uint16_t cy = (py - 50) >> 3;
   if (cx >= COLS || cy >= ROWS) return 1;
-  return world[cy][cx] == CHAR_BLOCK;
+  return is_wall((uint8_t)cy, (uint8_t)cx);
 }
 
 static void wait_vblank(void) {
@@ -135,15 +180,12 @@ void main(void) {
   uint8_t pad;
 
   copy_sprite();
-  SPRITE_POINTERS[0] = 0x20;  /* $0800 / $40 */
+  SPRITE_POINTERS[0] = 0x80;  /* $2000 / 64 */
 
   WR(VIC_BORDER, 0x00);
   WR(VIC_BG0,    0x00);
   WR(VIC_SPR_COL(0), COL_RED);
 
-  world_build();
-  world_draw();
-
   WR(VIC_SPRITE_X(0), (uint8_t)(sx & 0xFF));
   WR(VIC_SPRITE_Y(0), (uint8_t)sy);
   WR(VIC_SPR_ENA, 0x01);
@@ -152,6 +194,14 @@ void main(void) {
     uint16_t nx = sx, ny = sy;
     wait_vblank();
 
+    /* Repaint the whole character map every frame. The KERNAL keeps
+     * clearing screen RAM for the first frames after boot, so a single
+     * draw before the loop gets wiped (almost-blank screen). Redrawing
+     * each frame is cheap (1000 cells) and guarantees the world is always
+     * on-screen regardless of boot timing — the same "redraw every frame"
+     * discipline the other scaffolds use. */
+    world_draw();
+
     pad = ~RD(CIA1_PRA) & 0x0F;
     if (pad & JOY_UP    && sy > 52)  ny--;
     if (pad & JOY_DOWN  && sy < 240) ny++;

package/examples/gb/templates/default.c

@@ -1,11 +1,17 @@
 /* ── default.c — minimal Game Boy (DMG) starter ───────────────────
  *
- * Boots the LCD, cycles the DMG background palette through 4 shade
- * arrangements via BGP ($FF47). Smallest possible "ROM that does
- * something visible" — use this as the starting point when you're
- * not yet sure what you want to build.
+ * A "hello, it works!" screen: a tiled background (a dithered field with
+ * two bands + a centre box) plus a sprite that bounces around. The very
+ * first build shows recognizable content — not a flat colour. The DMG
+ * background palette (BGP, $FF47) also cycles through 4 shade
+ * arrangements so you can SEE the palette path is alive. Use this as the
+ * starting point when you're not yet sure what you want to build.
  *
  * GB-specific notes for the agent:
+ *   - 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.
  *   - DMG uses the BGP/OBP0/OBP1 registers — NOT the CGB BCPS/BCPD
  *     palette RAM. The GBC tree's default uses BCPS; don't copy that
  *     into a DMG project or your screen will stay one shade.
@@ -28,31 +34,119 @@
 #include "gb_hardware.h"
 #include "gb_runtime.h"
 
-/* Four BGP arrangements; each byte packs 4 color indices, 2 bits each:
- *   bits 7-6 = color for tile-index 3 (darkest source)
- *   bits 5-4 = color for tile-index 2
- *   bits 3-2 = color for tile-index 1
- *   bits 1-0 = color for tile-index 0 (lightest source)
- * Color: 0 = white, 1 = light grey, 2 = dark grey, 3 = black. */
+/* Six 8×8 tiles, 2bpp (16 bytes each: row N = byte 2N low-plane, 2N+1
+ * high-plane). The colour index per pixel (0..3) selects a shade through
+ * BGP. We spread indices 1, 2 and 3 across the screen spatially so no
+ * single shade ever fills the frame — regardless of the BGP arrangement.
+ *   tile 0 — blank   (all index 0)
+ *   tile 1 — solid index 1   (top band)
+ *   tile 2 — solid index 2   (bottom band)
+ *   tile 3 — dither idx1/idx2 (the textured backdrop — mixes two shades
+ *            inside every cell so the field is never flat)
+ *   tile 4 — solid index 3   (centre box + border)
+ *   tile 5 — sprite diamond (index 3) */
+static const uint8_t tiles[6 * 16] = {
+  /* 0: blank */
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* 1: solid index 1 (low plane on, high plane off) */
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  /* 2: solid index 2 (low plane off, high plane on) */
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+  /* 3: dither — checkerboard of index 1 and index 2 */
+  0x55,0xAA, 0xAA,0x55, 0x55,0xAA, 0xAA,0x55,
+  0x55,0xAA, 0xAA,0x55, 0x55,0xAA, 0xAA,0x55,
+  /* 4: solid index 3 (both planes on) */
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+  /* 5: diamond in index 3 (both planes set on the diamond pixels) */
+  0x18,0x18, 0x3C,0x3C, 0x7E,0x7E, 0xFF,0xFF,
+  0xFF,0xFF, 0x7E,0x7E, 0x3C,0x3C, 0x18,0x18,
+};
+
+#define T_BLANK   0
+#define T_BAND1   1
+#define T_BAND2   2
+#define T_FIELD   3
+#define T_BOX     4
+#define T_SPRITE  5
+
+/* Four BGP arrangements; each byte packs 4 colour indices, 2 bits each:
+ *   bits 7-6 = shade for index 3,  bits 5-4 = index 2,
+ *   bits 3-2 = index 1,            bits 1-0 = index 0.
+ * Shade: 0 = white, 1 = light grey, 2 = dark grey, 3 = black.
+ * Every entry keeps index 1 != index 2 so the dithered field always shows
+ * two distinct shades (the screen is never one flat colour, even mid-cycle). */
 static const uint8_t bgp_shades[4] = {
-  0xE4,   /* normal:       3=black 2=dark  1=light 0=white */
-  0x90,   /* inverted-ish: 3=dark  2=light 1=white 0=white */
-  0x39,   /* shifted:      3=white 2=dark  1=dark  0=light */
-  0x00,   /* all-white (DMG visible: "off"-looking screen) */
+  0xE4,   /* normal:    3=black 2=dark  1=light 0=white */
+  0x90,   /* dim:       3=dark  2=light 1=white 0=white */
+  0x39,   /* shifted:   3=white 2=dark  1=dark  0=light */
+  0x1B,   /* inverted:  3=white 2=light 1=dark  0=black */
 };
 
+static void upload_tiles(void) {
+  memcpy_vram((void *)0x8000, tiles, sizeof(tiles));
+}
+
+/* Paint the BG map (32×32; we fill the visible 20×18). A dithered field
+ * everywhere, two solid bands, a solid border and a centre box, so the
+ * screen reads as real content rather than a flat shade. */
+static void draw_backdrop(void) {
+  uint8_t *bg = BG_MAP_0;       /* $9800 */
+  uint8_t x, y;
+  for (y = 0; y < 18; y++)
+    for (x = 0; x < 20; x++)
+      bg[y * 32 + x] = T_FIELD;
+  for (x = 0; x < 20; x++) {
+    bg[0  * 32 + x] = T_BOX;    /* top border  */
+    bg[17 * 32 + x] = T_BOX;    /* bottom border */
+    bg[3  * 32 + x] = T_BAND1;  /* upper band  */
+    bg[14 * 32 + x] = T_BAND2;  /* lower band  */
+  }
+  for (y = 0; y < 18; y++) {
+    bg[y * 32 + 0]  = T_BOX;    /* left border  */
+    bg[y * 32 + 19] = T_BOX;    /* right border */
+  }
+  for (y = 7; y < 11; y++)
+    for (x = 7; x < 13; x++)
+      bg[y * 32 + x] = T_BOX;   /* centre box   */
+}
+
 void main(void) {
   uint8_t shade = 0;
   uint16_t frame = 0;
+  uint8_t sx = 76, sy = 64;        /* sprite screen position */
+  int8_t  dx = 1,  dy = 1;          /* sprite velocity */
+
+  lcd_init_default();   /* LCD on, BGP=0xE4, BG+OBJ enabled */
+  LCDC = 0;
+
+  upload_tiles();
+  BGP = bgp_shades[0];
+  draw_backdrop();
 
-  lcd_init_default();   /* turns LCD on with BGP=0xE4, BG+OBJ enabled */
+  oam_clear();
+  oam_set(0, (uint8_t)(sy + 16), (uint8_t)(sx + 8), T_SPRITE, 0);
+
+  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 */
+    if ((frame & 0x1F) == 0) {       /* every 32 frames: cycle BGP */
       shade = (uint8_t)((shade + 1) & 0x03);
       BGP = bgp_shades[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), T_SPRITE, 0);
   }
 }

package/examples/gb/templates/hello_sprite.c

@@ -47,6 +47,8 @@ void main(void) {
   uint8_t i;
   uint8_t *vram_dst;
   const uint8_t *src;
+  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
@@ -60,9 +62,16 @@ void main(void) {
    * accidentally render garbage tiles that point to it. */
   vram_dst = (uint8_t *)0x8010;
   src = tile_data;
-  for (i = 0; i < 16; i++) {
-    vram_dst[i] = src[i];
-  }
+  /* memcpy_vram (pointer-walk) — NOT an indexed vram_dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when the dest points into VRAM ($8000-$9FFF). */
+  memcpy_vram(vram_dst, src, 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. memcpy_vram-style
+   * pointer walk (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
@@ -92,9 +101,9 @@ void main(void) {
   oam_dma_flush();      /* first OAM live before the screen turns on */
 
   /* ── 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/gb/templates/music_demo.c

@@ -29,11 +29,47 @@
  * project template). */
 extern const huge_song_t sample_song;
 
+/* Two 8×8 2bpp tiles so the BG isn't a single flat colour (a uniform
+ * screen reads >=92% one colour and fails the blank-screen check):
+ *   tile 1 — solid colour 3
+ *   tile 2 — solid colour 1
+ * We checkerboard them across the BG map below. */
+static const uint8_t tile_solid3[16] = {
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+  0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF, 0xFF,0xFF,
+};
+static const uint8_t tile_solid1[16] = {
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+};
+
 void main(void) {
   uint8_t  shade = 0;
   uint16_t frame = 0;
+  uint8_t *bg_map;
+  uint16_t j;
 
   lcd_init_default();
+  LCDC = 0;               /* LCD off so we can write VRAM freely */
+
+  /* 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_solid3, 16);
+  memcpy_vram((uint8_t *)0x8020, tile_solid1, 16);
+
+  /* Checkerboard the 32×32 BG map at $9800 with tiles 1 and 2 so the
+   * screen shows two distinct shades. 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));
+  }
+
+  /* LCD on with BG enabled, $8000 tile-data addressing so index 1 == our
+   * tile at $8010. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_TILE_DATA_LO;
+
   sound_init();
 
   hUGE_init(&sample_song);

package/examples/gb/templates/platformer.c

@@ -25,9 +25,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;
 
@@ -58,8 +75,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) {
@@ -71,8 +89,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;
@@ -81,7 +101,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 */
         }
     }
 }
@@ -108,6 +128,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/gb/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;