romdevtools 0.16.0 → 0.21.0

package/examples/atari7800/templates/shmup.c

@@ -20,6 +20,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -50,6 +52,39 @@ MK_DL(dl_row4); MK_DL(dl_row5); MK_DL(dl_row6); MK_DL(dl_row7);
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Background playfield ─────────────────────────────────────────
+ * Without a full-screen drawable the display list emits only the
+ * ship and ~99% of the screen stays the flat BACKGRND colour (reads
+ * as "blank"). These full-width bands fill the non-ship zones with a
+ * starfield-style background so the frame has real content.
+ *
+ * A single DL drawable is at most 32 bytes = 128 px wide, so a full
+ * 160-px line needs TWO drawables. Width = byte[3] low 5 bits (32-n);
+ * high 3 bits = palette. */
+static const uint8_t band_pix[32] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+#define MK_BAND(name, pal) static uint8_t name[11] = { \
+  0, 0x40, 0, ((pal) << 5) | 0,  0,    /* 128 px @ x0   */ \
+  0, 0x40, 0, ((pal) << 5) | 24, 128,  /* 32 px  @ x128 */ \
+  0 }
+MK_BAND(dl_field, 1);
+MK_BAND(dl_ground, 2);
+#define GROUND_ZONE 188
+
+static void set_band_addr(uint8_t* dl) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl[0] = dl[5] = (uint8_t)(a & 0xFF);
+  dl[2] = dl[7] = (uint8_t)(a >> 8);
+}
+
+static uint16_t bg_zone_dl(int zone) {
+  if (zone >= GROUND_ZONE) return (uint16_t)(uintptr_t)dl_ground;
+  if (zone >= 28)          return (uint16_t)(uintptr_t)dl_field;
+  return (uint16_t)(uintptr_t)dl_empty;
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -74,7 +109,6 @@ static void set_x(uint8_t x) {
 }
 
 static void build_dll(int y) {
-  uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   int i;
   for (i = 0; i < DLL_ZONES; i++) {
     uint16_t dl;
@@ -88,7 +122,7 @@ static void build_dll(int y) {
       case 5: dl = (uint16_t)(uintptr_t)dl_row5; break;
       case 6: dl = (uint16_t)(uintptr_t)dl_row6; break;
       case 7: dl = (uint16_t)(uintptr_t)dl_row7; break;
-      default: dl = empty; break;
+      default: dl = bg_zone_dl(i); break;
     }
     set_dll_entry(i, dl);
   }
@@ -111,6 +145,8 @@ void main(void) {
   set_dl_addr(dl_row5, ship_row5);
   set_dl_addr(dl_row6, ship_row6);
   set_dl_addr(dl_row7, ship_row7);
+  set_band_addr(dl_field);
+  set_band_addr(dl_ground);
 
   player_x = 80;
   player_y = 180;
@@ -121,6 +157,8 @@ void main(void) {
   P0C1     = 0x0F;
   P0C2     = 0x1C;
   P0C3     = 0x46;
+  P1C1     = 0x84;   /* upper nebula band (deep blue) */
+  P2C1     = 0x82;   /* lower nebula band (darker blue) */
   CHARBASE = 0;
   OFFSET   = 0;
 

package/examples/atari7800/templates/sports.c

@@ -21,6 +21,8 @@
 #define P0C1      (*(volatile uint8_t*)0x21)
 #define P0C2      (*(volatile uint8_t*)0x22)
 #define P0C3      (*(volatile uint8_t*)0x23)
+#define P1C1      (*(volatile uint8_t*)0x25)
+#define P2C1      (*(volatile uint8_t*)0x29)
 #define MSTAT     (*(volatile uint8_t*)0x28)
 #define DPPH      (*(volatile uint8_t*)0x2C)
 #define DPPL      (*(volatile uint8_t*)0x30)
@@ -60,6 +62,29 @@ static uint8_t scanline_dls[PLAY_LINES * DL_BYTES_PER_LINE];
 
 static uint8_t dl_empty[2] = { 0, 0 };
 
+/* ── Court border bands ───────────────────────────────────────────
+ * The court itself (per-scanline DLs below) only draws two thin
+ * paddles + a ball, so on a black screen ~99% of the frame is blank.
+ * Fill the zones above and below the court with full-width bands so
+ * the court is framed by visible walls. A single DL drawable is at
+ * most 32 bytes = 128 px wide, so a full 160-px line needs TWO
+ * drawables. Width = byte[3] low 5 bits (32-n); high 3 bits = palette. */
+static const uint8_t band_pix[32] = {
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,
+  0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55,0x55
+};
+#define MK_BAND(name, pal) static uint8_t name[11] = { \
+  0, 0x40, 0, ((pal) << 5) | 0,  0,    /* 128 px @ x0   */ \
+  0, 0x40, 0, ((pal) << 5) | 24, 128,  /* 32 px  @ x128 */ \
+  0 }
+MK_BAND(dl_wall, 1);
+
+static void set_band_addr(uint8_t* dl) {
+  uint16_t a = (uint16_t)(uintptr_t)band_pix;
+  dl[0] = dl[5] = (uint8_t)(a & 0xFF);
+  dl[2] = dl[7] = (uint8_t)(a >> 8);
+}
+
 #define DLL_ZONES 243
 static uint8_t dll[DLL_ZONES * 3];
 
@@ -92,19 +117,23 @@ static uint8_t emit_obj(uint8_t* dl, uint8_t off, uint16_t data_addr,
 
 /* Rebuild ALL scanline DLs + DLL based on current object positions. */
 static void rebuild(void) {
+  uint16_t wall = (uint16_t)(uintptr_t)dl_wall;
   uint16_t empty = (uint16_t)(uintptr_t)dl_empty;
   uint16_t solid = (uint16_t)(uintptr_t)solid_row;
   int line;
   int i;
 
-  /* DLL: point each play-area line at its scanline DL slot; everything
-   * else at the empty DL. */
+  /* DLL: point each play-area line at its scanline DL slot; frame the
+   * court with full-width wall bands above and below, leaving a thin
+   * empty gutter right at the court edges. */
   for (i = 0; i < DLL_ZONES; i++) {
     if (i >= COURT_TOP && i < COURT_BOT) {
       uint16_t dlp = (uint16_t)(uintptr_t)&scanline_dls[(i - COURT_TOP) * DL_BYTES_PER_LINE];
       set_dll_entry(i, dlp);
+    } else if (i >= COURT_TOP - 8 && i < COURT_BOT + 8) {
+      set_dll_entry(i, empty);   /* small gutter around the court */
     } else {
-      set_dll_entry(i, empty);
+      set_dll_entry(i, wall);
     }
   }
 
@@ -151,13 +180,15 @@ void main(void) {
   p1y = 110; p2y = 110;
   serve_ball(0);
 
-  BACKGRND = 0x00;   /* black */
-  P0C1     = 0x0F;   /* white sprite */
+  BACKGRND = 0x00;   /* black court */
+  P0C1     = 0x0F;   /* white paddles + ball */
   P0C2     = 0x0F;
   P0C3     = 0x0F;
+  P1C1     = 0x48;   /* court walls (blue) */
   CHARBASE = 0;
   OFFSET   = 0;
 
+  set_band_addr(dl_wall);
   rebuild();
 
   dll_addr = (uint16_t)(uintptr_t)dll;

package/examples/c64/templates/platformer.c

@@ -96,10 +96,24 @@ static void render_view(uint8_t coarseCol) {
       uint16_t off = (uint16_t)r * 40 + sc;
       if (wc < WORLD_COLS && world_is_wall((uint8_t)wc, r)) {
         SCREEN[off] = 0xA0;          /* reverse-space solid block */
-        COLORS[off] = 0x0C;          /* mid grey */
+        COLORS[off] = 0x0C;          /* mid grey platform */
+      } else if (r >= 22) {
+        /* Ground fill below the floor row: dithered earth so the lower
+         * band reads as solid terrain, not void. */
+        SCREEN[off] = 0xA0;
+        COLORS[off] = (((uint8_t)wc ^ r) & 1) ? 0x09 : 0x08;  /* brown / orange */
       } else {
-        SCREEN[off] = 0x20;          /* space */
-        COLORS[off] = 0x06;          /* bg color */
+        /* Textured sky so two colours share the backdrop and neither the
+         * sky nor the border dominates the frame. Sparse '.' stars on a
+         * coarse lattice add detail; reverse-space everywhere else gives a
+         * filled (non-blank) sky band that scrolls with the world. */
+        if (((wc * 3u + r * 7u) % 23u) == 0u) {
+          SCREEN[off] = 0x2E;        /* '.' distant detail */
+          COLORS[off] = 0x01;        /* white */
+        } else {
+          SCREEN[off] = 0xA0;        /* solid block sky */
+          COLORS[off] = (((uint8_t)wc ^ (r >> 1)) & 1) ? 0x06 : 0x0E;  /* blue / light blue */
+        }
       }
     }
   }
@@ -133,8 +147,8 @@ void main(void) {
   copy_sprite(0, player_sprite);
   SPRITE_POINTERS[0] = 0x80;  /* $2000/64 */
   POKE(VIC_SPR_COL(0), 0x07);  /* yellow player */
-  POKE(VIC_BORDER, 0x06);      /* dark blue */
-  POKE(VIC_BG0,    0x06);
+  POKE(VIC_BORDER, 0x00);      /* black border frames the scene */
+  POKE(VIC_BG0,    0x06);      /* sky-blue (shows through any gaps) */
 
   render_view(0);              /* paint the initial 40-col view */
 

package/examples/c64/templates/puzzle.c

@@ -40,6 +40,35 @@ static void wait_vblank(void) {
   while (PEEK(VIC_RASTER) >= 250) { }
 }
 
+/* Paint the playfield surround so the board reads as a real puzzle screen
+ * instead of a tiny well floating in a black void: a dithered backdrop fills
+ * the whole 40x25 matrix (two dark blues, so two colours share the screen
+ * and neither dominates), then a bright frame is drawn one cell outside the
+ * 6x12 well, and the well interior is cleared to black so the falling blocks
+ * pop. Call ONCE before draw_grid(); draw_grid() owns the interior after. */
+static void draw_field(void) {
+  uint16_t i;
+  uint8_t r, c;
+  int8_t  fr, fc;
+  for (i = 0; i < 1000; i++) {
+    SCREEN[i] = 0xA0;                       /* solid block backdrop */
+    COLORS[i] = ((i ^ (i >> 5)) & 1) ? 0x06 : 0x0E;  /* blue / light blue */
+  }
+  /* Bright frame one cell outside the well. */
+  for (fc = -1; fc <= COLS; fc++) {
+    r = (uint8_t)(GRID_R - 1);       SCREEN[r * 40 + GRID_C + fc] = 0xA0; COLORS[r * 40 + GRID_C + fc] = 0x01;
+    r = (uint8_t)(GRID_R + ROWS);    SCREEN[r * 40 + GRID_C + fc] = 0xA0; COLORS[r * 40 + GRID_C + fc] = 0x01;
+  }
+  for (fr = -1; fr <= ROWS; fr++) {
+    r = (uint8_t)(GRID_R + fr);
+    SCREEN[r * 40 + GRID_C - 1]   = 0xA0; COLORS[r * 40 + GRID_C - 1]   = 0x01;
+    SCREEN[r * 40 + GRID_C + COLS] = 0xA0; COLORS[r * 40 + GRID_C + COLS] = 0x01;
+  }
+  /* Clear the well interior to black so colored blocks stand out. */
+  for (r = 0; r < ROWS; r++)
+    for (c = 0; c < COLS; c++) SCREEN[(GRID_R + r) * 40 + GRID_C + c] = ' ';
+}
+
 static uint8_t rng_pick(void) {
   rng = rng * 1103515245u + 12345u;
   return (uint8_t)(1 + (rng >> 16) % 3);
@@ -131,14 +160,15 @@ static void lock_piece(void) {
 
 void main(void) {
   uint8_t r, c, pad, prev = 0, fall_rate, t;
-  POKE(VIC_BORDER, 0x00);
-  POKE(VIC_BG0,    0x00);
+  POKE(VIC_BORDER, 0x06);   /* blue border frames the playfield */
+  POKE(VIC_BG0,    0x00);   /* black well interior so blocks pop */
 
   for (r = 0; r < ROWS; r++)
     for (c = 0; c < COLS; c++) grid[r][c] = 0;
 
   score = 0; fall_timer = 0;
   sfx_init();
+  draw_field();             /* paint the textured surround + well frame */
   new_piece();
   draw_grid();
 

package/examples/c64/templates/shmup.c

@@ -19,6 +19,9 @@
 #define POKE(addr, val) (*(volatile uint8_t*)(addr) = (val))
 #define PEEK(addr)      (*(volatile uint8_t*)(addr))
 
+#define SCREEN ((volatile uint8_t*)0x0400)
+#define COLORS ((volatile uint8_t*)0xD800)
+
 #define SPRITE_POINTERS  ((volatile uint8_t*)0x07F8)
 #define SPRITE_DATA_BASE 0x2000  /* sprite N data at $2000 + N*64 — NOT $0800,
                                   * which collides with the $0801 .prg load (C64-1) */
@@ -105,6 +108,28 @@ static void wait_vblank(void) {
   while (PEEK(VIC_RASTER) >= 250) { }
 }
 
+/* Paint a deep-space backdrop into the 40x25 character matrix so the
+ * playfield reads as space instead of a flat black void. Every cell gets
+ * a dithered "nebula" char (reverse-space 0xA0) in one of two dark blues,
+ * so two colours share the screen and no single colour dominates. A sparse
+ * scatter of bright '.' stars (drawn as a normal glyph over the dither)
+ * adds twinkle. Cosmetic only — sprites still move over the top. */
+static void draw_starfield(void) {
+  uint16_t i;
+  uint8_t r, c;
+  for (i = 0; i < 1000; i++) {
+    SCREEN[i] = 0xA0;                       /* solid block fills the cell  */
+    COLORS[i] = ((i ^ (i >> 5)) & 1) ? 0x06 : 0x0B;  /* blue / dark grey   */
+  }
+  /* Scatter stars on a coarse lattice so ~1 in 12 cells twinkles. */
+  for (r = 1; r < 25; r += 3) {
+    for (c = (uint8_t)(r * 5u % 7u); c < 40; c += 7) {
+      SCREEN[r * 40 + c] = 0x2E;            /* '.' star glyph              */
+      COLORS[r * 40 + c] = ((r + c) & 1) ? 0x01 : 0x0F;  /* white / l.grey */
+    }
+  }
+}
+
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
   volatile uint8_t *dst = (volatile uint8_t*)(SPRITE_DATA_BASE + slot * 64);
@@ -130,8 +155,9 @@ void main(void) {
   for (i = 0; i < MAX_BULLETS; i++) POKE(VIC_SPR_COL(SLOT_BULLET0 + i), 0x01);  /* white */
   for (i = 0; i < MAX_ENEMIES; i++) POKE(VIC_SPR_COL(SLOT_ENEMY0  + i), 0x02);  /* red */
 
-  POKE(VIC_BORDER, 0x00);
-  POKE(VIC_BG0, 0x00);
+  POKE(VIC_BORDER, 0x00);   /* black border frames the starfield */
+  POKE(VIC_BG0, 0x06);      /* deep-blue space background */
+  draw_starfield();         /* paint the textured space backdrop */
 
   player.x = 152; player.y = 200; player.alive = 1;
   for (i = 0; i < MAX_BULLETS; i++) bullets[i].alive = 0;

package/examples/c64/templates/sports.c

@@ -11,6 +11,9 @@
 #define POKE(addr, val) (*(volatile uint8_t*)(addr) = (val))
 #define PEEK(addr)      (*(volatile uint8_t*)(addr))
 
+#define SCREEN ((volatile uint8_t*)0x0400)
+#define COLORS ((volatile uint8_t*)0xD800)
+
 #define JOY_UP    0x01
 #define JOY_DOWN  0x02
 
@@ -39,6 +42,30 @@ static void wait_vblank(void) {
   while (PEEK(VIC_RASTER) >= 250) { }
 }
 
+/* Paint a Pong court into the 40x25 character matrix so the table reads as
+ * a real court instead of a flat black void: a dithered green playfield
+ * (two greens, so two colours share the screen and neither dominates),
+ * solid top/bottom boundary rails, and a dashed centre net. Cosmetic only —
+ * the paddle/ball sprites move over the top. */
+static void draw_court(void) {
+  uint16_t i;
+  uint8_t r, c;
+  /* Dithered green playfield fills every cell. */
+  for (i = 0; i < 1000; i++) {
+    SCREEN[i] = 0xA0;                       /* solid block */
+    COLORS[i] = ((i ^ (i >> 5)) & 1) ? 0x05 : 0x09;  /* green / brown    */
+  }
+  /* Top + bottom boundary rails (rows 1 and 23) in white. */
+  for (c = 0; c < 40; c++) {
+    SCREEN[1 * 40 + c]  = 0xA0; COLORS[1 * 40 + c]  = 0x01;
+    SCREEN[23 * 40 + c] = 0xA0; COLORS[23 * 40 + c] = 0x01;
+  }
+  /* Dashed centre net (column 20). */
+  for (r = 2; r < 23; r++) {
+    if (r & 1) { SCREEN[r * 40 + 20] = 0xA0; COLORS[r * 40 + 20] = 0x01; }
+  }
+}
+
 static void copy_sprite(uint8_t slot, const uint8_t *data) {
   uint8_t i;
   volatile uint8_t *dst = (volatile uint8_t*)(0x2000 + slot * 64);  /* $2000, not $0800 (collides w/ $0801 .prg) */
@@ -63,8 +90,9 @@ void main(void) {
   POKE(VIC_SPR_COL(1), 0x01);
   POKE(VIC_SPR_COL(2), 0x07);  /* yellow ball */
 
-  POKE(VIC_BORDER, 0x00);
-  POKE(VIC_BG0,    0x00);
+  POKE(VIC_BORDER, 0x00);   /* black border frames the court */
+  POKE(VIC_BG0,    0x05);   /* green court background */
+  draw_court();             /* paint the textured Pong court */
 
   /* P1 paddle on left, P2 on right. */
   POKE(VIC_SPRITE_X(0), 30);

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/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;
 
@@ -71,8 +88,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 +100,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 +127,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. */
@@ -131,6 +145,20 @@ static void upload_tile(uint8_t slot, const uint8_t *src) {
     for (i = 0; i < 16; i++) dst[i] = src[i];
 }
 
+/* Draw the well frame around the 6×12 play area. Grid cells live at
+ * map[(row+1)*32 + (col+7)] (rows 1..12, cols 7..12), so the frame is the
+ * column to each side (6 and 13) and the floor row just below (row 13). */
+static void draw_well(void) {
+    uint8_t *map = (uint8_t *)0x9800;
+    uint8_t r;
+    for (r = 1; r <= 12; r++) {
+        map[r * 32 + 6]  = T_WALL;   /* left wall  */
+        map[r * 32 + 13] = T_WALL;   /* right wall */
+    }
+    for (r = 6; r <= 13; r++)
+        map[13 * 32 + r] = T_WALL;   /* floor      */
+}
+
 void main(void) {
     uint8_t pad, prev = 0, fall_rate, t;
     int16_t r, c;
@@ -145,6 +173,7 @@ void main(void) {
     upload_tile(T_R,     tile_r);
     upload_tile(T_G,     tile_g);
     upload_tile(T_B,     tile_b);
+    upload_tile(T_WALL,  tile_wall);
 
     BCPS = 0x80;
     for (i = 0; i < 4; i++) {
@@ -165,6 +194,7 @@ void main(void) {
     score = 0;
     fall_timer = 0;
     new_piece();
+    draw_well();
     draw_grid();
 
     LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_TILE_DATA_LO;