romdevtools 0.16.0 → 0.21.0

package/examples/sms/templates/puzzle.c

@@ -25,16 +25,19 @@ extern uint8_t sms_joypad_read(void);
 #define T_R     1
 #define T_G     2
 #define T_B     3
+#define T_WALL  4   /* well border        */
+#define T_FIELD 5   /* empty well interior */
 
 static const uint8_t palette[32] = {
-  /* BG palette: backdrop black, red, green, blue */
-  0x00,0x03,0x0C,0x30, 0x00,0x00,0x00,0x00,
+  /* BG palette: 0 backdrop navy, 1 red, 2 green, 3 blue, 4 wall grey,
+   * 5 dim field blue */
+  0x10,0x03,0x0C,0x30, 0x15,0x14, 0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
 };
 
-static const uint8_t bg_tiles[32 * 4] = {
+static const uint8_t bg_tiles[32 * 6] = {
   /* T_BLANK */
   0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0,
   0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0,
@@ -53,6 +56,16 @@ static const uint8_t bg_tiles[32 * 4] = {
   0xFF,0xFF,0x00,0x00, 0xFF,0xFF,0x00,0x00,
   0xFF,0xFF,0x00,0x00, 0xFF,0xFF,0x00,0x00,
   0xFF,0xFF,0x00,0x00, 0xFF,0xFF,0x00,0x00,
+  /* T_WALL — colour 4 fill (plane 2 set) */
+  0x00,0x00,0xFF,0x00, 0x00,0x00,0xFF,0x00,
+  0x00,0x00,0xFF,0x00, 0x00,0x00,0xFF,0x00,
+  0x00,0x00,0xFF,0x00, 0x00,0x00,0xFF,0x00,
+  0x00,0x00,0xFF,0x00, 0x00,0x00,0xFF,0x00,
+  /* T_FIELD — colour 5 fill (planes 0+2 set) = dim field */
+  0xFF,0x00,0xFF,0x00, 0xFF,0x00,0xFF,0x00,
+  0xFF,0x00,0xFF,0x00, 0xFF,0x00,0xFF,0x00,
+  0xFF,0x00,0xFF,0x00, 0xFF,0x00,0xFF,0x00,
+  0xFF,0x00,0xFF,0x00, 0xFF,0x00,0xFF,0x00,
 };
 
 static uint8_t grid[ROWS][COLS];
@@ -76,7 +89,7 @@ static uint8_t tile_for(uint8_t c) {
   if (c == 1) return T_R;
   if (c == 2) return T_G;
   if (c == 3) return T_B;
-  return T_BLANK;
+  return T_FIELD;   /* empty cell shows the dim well interior, not backdrop */
 }
 
 static void draw_cell(int8_t col, int8_t row, uint8_t cell) {
@@ -85,6 +98,21 @@ static void draw_cell(int8_t col, int8_t row, uint8_t cell) {
   sms_set_tilemap_cell((uint8_t)(row + 1), (uint8_t)(col + 7), tile_for(cell), 0);
 }
 
+/* Draw the well: a grey border frame around the 6x12 play field with a dim
+ * field interior, so the playfield is clearly visible even when empty.
+ * The grid maps cell (col,row) -> tilemap (row+1, col+7), i.e. rows 1..12
+ * cols 7..12. Frame the perimeter at rows 0..13, cols 6..13. */
+static void draw_well(void) {
+  uint8_t r, c;
+  for (r = 0; r <= 13; r++) {
+    for (c = 6; c <= 13; c++) {
+      uint8_t t = T_FIELD;
+      if (r == 0 || r == 13 || c == 6 || c == 13) t = T_WALL;
+      sms_set_tilemap_cell(r, c, t, 0);
+    }
+  }
+}
+
 static void draw_grid(void) {
   int8_t r, c;
   for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) draw_cell(c, r, grid[r][c]);
@@ -151,7 +179,7 @@ void main(void) {
 
   sms_vdp_init();
   sms_load_palette(palette);
-  sms_load_tiles(0x0000, bg_tiles, 32 * 4);
+  sms_load_tiles(0x0000, bg_tiles, 32 * 6);
 
   for (r = 0; r < 24; r++) for (c = 0; c < 32; c++) sms_set_tilemap_cell(r, c, T_BLANK, 0);
   for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) grid[r][c] = 0;
@@ -159,6 +187,7 @@ void main(void) {
   score = 0;
   fall_timer = 0;
   new_piece();
+  draw_well();
   draw_grid();
 
   sfx_init();

package/examples/sms/templates/racing.c

@@ -18,6 +18,7 @@ extern void    sms_vdp_init(void);
 extern void    sms_vdp_display_on(void);
 extern void    sms_load_palette(const uint8_t *palette);
 extern void    sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void    sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void    sms_vblank_wait(void);
 extern uint8_t sms_joypad_read(void);
 extern void    sms_sprite_init(void);
@@ -31,13 +32,47 @@ extern void    sms_sat_upload(void);
 #define MAX_OBSTACLES   4
 
 static const uint8_t palette[32] = {
-  0x10, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  /* BG: 0 = dark navy backdrop, 1 = grass green, 2 = road grey */
+  0x10, 0x08, 0x16, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   /* Sprite palette: white (1), red (2) */
   0x00, 0x3F, 0x03, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 };
 
+/* Three BG tiles for the track, loaded into the BG tile bank at $0000:
+ *   tile 0 = blank (backdrop), tile 1 = grass (colour 1), tile 2 = road
+ *   (colour 2). The track fills the whole 32x24 SMS screen so the display
+ *   is a clear road scene, not a flat backdrop. */
+static const uint8_t bg_tiles[96] = {
+  /* BG tile 0 = blank */
+  0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0,
+  0,0,0,0, 0,0,0,0, 0,0,0,0, 0,0,0,0,
+  /* BG tile 1 = grass (colour 1 -> plane 0 set) */
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  /* BG tile 2 = road (colour 2 -> plane 1 set) */
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+};
+
+/* Paint the whole 32x24 SMS screen: grey road down the centre lanes,
+ * green grass on the shoulders. BG tile bank is $0000. The road spans the
+ * three lanes (player X 72..184 -> roughly cols 8..23). */
+static void draw_track(void) {
+  uint8_t row, col;
+  for (row = 0; row < 24; row++) {
+    for (col = 0; col < 32; col++) {
+      uint8_t road = (col >= 8 && col <= 23);
+      sms_set_tilemap_cell(row, col, road ? 2 : 1, 0);
+    }
+  }
+}
+
 /* Two sprite tiles — player (colour 1) + enemy (colour 2). */
 static const uint8_t tiles[64] = {
   /* Tile 0 = player car (colour 1 → plane 0 set) */
@@ -97,7 +132,9 @@ void main(void) {
   uint8_t i;
   sms_vdp_init();
   sms_load_palette(palette);
-  sms_load_tiles(0x2000, tiles, 64);
+  sms_load_tiles(0x0000, bg_tiles, 96);   /* BG tiles -> BG bank $0000 */
+  sms_load_tiles(0x2000, tiles, 64);      /* sprite tiles -> sprite bank $2000 */
+  draw_track();
   sms_sprite_init();
   sfx_init();
   sms_vdp_display_on();

package/examples/sms/templates/shmup.c

@@ -15,6 +15,7 @@ extern void sms_vdp_display_on(void);
 extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
 extern void sms_load_palette(const uint8_t *palette);
 extern void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void sms_vblank_wait(void);
 extern uint8_t sms_joypad_read(void);
 extern void sms_sprite_init(void);
@@ -29,13 +30,49 @@ extern void sms_sat_upload(void);
 #define T_ENEMY  2
 
 static const uint8_t palette[32] = {
-  0x10,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* BG: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue, 3 = star white */
+  0x10,0x08,0x20,0x3F, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   /* Sprite palette: white, yellow, red */
   0x00,0x3F,0x0F,0x03, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
 };
 
+/* Three BG tiles for the starfield, loaded into the BG tile bank at $0000:
+ *   tile 0 = deep space (solid colour 1)
+ *   tile 1 = lighter space band (solid colour 2)
+ *   tile 2 = space with a star (mostly colour 1, one colour-3 pixel) */
+static const uint8_t bg_tiles[96] = {
+  /* tile 0 = deep space (colour 1 -> plane 0 set) */
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  /* tile 1 = lighter band (colour 2 -> plane 1 set) */
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  /* tile 2 = deep space + a star: row 3 col 3 = colour 3 (planes 0+1) */
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x10,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+};
+
+/* Paint the whole 32x24 SMS screen with a banded starfield so the screen
+ * is clearly space, not a flat backdrop. BG tile bank is $0000. */
+static void draw_starfield(void) {
+  uint8_t row, col;
+  for (row = 0; row < 24; row++) {
+    for (col = 0; col < 32; col++) {
+      uint8_t t = (row & 2) ? 1 : 0;             /* alternating depth bands */
+      if (((row * 7 + col * 5) & 7) == 0) t = 2; /* sparse stars */
+      sms_set_tilemap_cell(row, col, t, 0);
+    }
+  }
+}
+
 static const uint8_t sprite_tiles[32 * 3] = {
   /* T_SHIP — diamond using colour 1 (white) */
   0x18,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
@@ -96,7 +133,9 @@ void main(void) {
 
   sms_vdp_init();
   sms_load_palette(palette);
-  sms_load_tiles(0x2000, sprite_tiles, 32 * 3);
+  sms_load_tiles(0x0000, bg_tiles, 96);          /* BG tiles -> BG bank $0000 */
+  sms_load_tiles(0x2000, sprite_tiles, 32 * 3);  /* sprite tiles -> $2000 */
+  draw_starfield();
 
   player.x = 120; player.y = 160; player.alive = 1;
   {

package/examples/sms/templates/sports.c

@@ -20,6 +20,7 @@ extern void    sms_vdp_init(void);
 extern void    sms_vdp_display_on(void);
 extern void    sms_load_palette(const uint8_t *palette);
 extern void    sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void    sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void    sms_vblank_wait(void);
 extern uint8_t sms_joypad_read(void);
 extern uint8_t sms_joypad_read_p2(void);
@@ -35,7 +36,8 @@ extern void    sms_sat_upload(void);
 #define PADDLE_X2   232
 
 static const uint8_t palette[32] = {
-  0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  /* BG: 0 = backdrop, 1 = court green, 2 = court line / net white */
+  0x10, 0x08, 0x3F, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   /* Sprite palette: white at idx 1 */
   0x00, 0x3F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
@@ -49,6 +51,43 @@ static const uint8_t tile_solid[32] = {
   0xFF, 0x00, 0x00, 0x00, 0xFF, 0x00, 0x00, 0x00,
 };
 
+/* Three BG tiles for the court, loaded into the BG tile bank at $0000:
+ *   tile 0 = court green (solid colour 1)
+ *   tile 1 = court line / border (solid colour 2 = white)
+ *   tile 2 = dashed net (colour 2 vertical stripe on green) */
+static const uint8_t bg_tiles[96] = {
+  /* tile 0 = court green (colour 1 -> plane 0 set) */
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  /* tile 1 = court line / border (colour 2 -> plane 1 set) */
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  0x00,0xFF,0x00,0x00, 0x00,0xFF,0x00,0x00,
+  /* tile 2 = net: centre column colour 2, rest colour 1 (green) */
+  0xFF,0x18,0x00,0x00, 0xFF,0x18,0x00,0x00,
+  0xFF,0x18,0x00,0x00, 0xFF,0x18,0x00,0x00,
+  0xFF,0x18,0x00,0x00, 0xFF,0x18,0x00,0x00,
+  0xFF,0x18,0x00,0x00, 0xFF,0x18,0x00,0x00,
+};
+
+/* Paint the whole 32x24 court: green field, white top/bottom border lines,
+ * and a dashed net down the centre column. BG tile bank is $0000. */
+static void draw_court(void) {
+  uint8_t row, col;
+  for (row = 0; row < 24; row++) {
+    for (col = 0; col < 32; col++) {
+      uint8_t t = 0;                              /* green field          */
+      if (row <= 1 || row >= 22) t = 1;           /* white top/bottom lines */
+      else if (col == 1 || col == 30) t = 1;      /* white sidelines        */
+      else if (col == 16) t = 2;                  /* solid centre net       */
+      sms_set_tilemap_cell(row, col, t, 0);
+    }
+  }
+}
+
 static int16_t p1y, p2y, bx, by;
 static int8_t  bdx, bdy;
 static uint8_t score_p1, score_p2;
@@ -72,7 +111,9 @@ void main(void) {
   uint8_t i;
   sms_vdp_init();
   sms_load_palette(palette);
-  sms_load_tiles(0x2000, tile_solid, 32);
+  sms_load_tiles(0x0000, bg_tiles, 96);     /* BG court tiles -> BG bank $0000 */
+  sms_load_tiles(0x2000, tile_solid, 32);   /* paddle/ball sprite tile -> $2000 */
+  draw_court();
   sms_sprite_init();
   sfx_init();
   sms_vdp_display_on();

package/examples/snes/templates/default.c

@@ -1,61 +1,83 @@
 /* default.c — SNES PVSnesLib starter (C).
  *
- * Smallest "ROM that does something visible" — sets a blue backdrop
- * and parks a white diamond sprite in the centre of the screen.
- * Pressing the d-pad moves the sprite.
+ * Smallest "ROM that does something visible": a full-screen diamond-tile
+ * background (BG0) with a movable white sprite parked in the centre.
+ * Pressing the d-pad moves the sprite. The tiled backdrop means the very
+ * first build shows recognizable content, not a flat colour — the SNES
+ * equivalent of the "is anything even rendering?" smoke test.
  *
  * Picked as the default SNES template because:
- *   - PVSnesLib gives a clean C API (oamSet, padsCurrent, etc.)
+ *   - PVSnesLib gives a clean C API (bgInitTileSet, oamSet, padsCurrent…)
  *     instead of raw 65816 / direct register pokes.
  *   - tcc-65816 builds it in <2s.
- *   - You read this file once and know how every SNES C scaffold
- *     is structured (hello_sprite, shmup, platformer all extend it).
+ *   - You read this file once and know how every SNES C scaffold is
+ *     structured (hello_sprite, shmup, platformer all extend it).
+ *
+ * The one footgun this guards against: on the SNES, NOTHING renders until
+ * setScreenOn() lifts forced blank (INIDISP $80) AND at least one layer
+ * (a BG or the sprite layer) actually has tiles + a non-black palette.
+ * Disabling every BG and showing one sprite (the obvious "minimal" move)
+ * leaves a near-blank screen — so here we light up BG0 too.
  *
- * For raw 65816 see template:"asm" (kept for cycle-accurate work).
  * For text-mode console output see template:"c_hello".
- * For genre-shaped scaffolds see createGame({genre:"shmup", ...}).
+ * For raw 65816 see template:"asm" (kept for cycle-accurate work).
+ * For genre-shaped scaffolds see scaffold({op:'game', genre:"shmup", ...}).
  *
- * Sibling `data.asm` provides the sprite tile + palette bytes.
- * Build:
- *   build({ output: "rom", 
- *     platform:"snes", language:"c",
- *     sourcesPaths:{"main.c":"...","data.asm":"..."},
- *   })
+ * Sibling `data.asm` provides tilsprite (one 8×8 4bpp diamond tile) +
+ * palsprite (its 16-colour palette). We reuse that one tile for BOTH the
+ * sprite and the BG wallpaper — replace with real gfx4snes .pic/.pal art.
  */
 #include <snes.h>
 
 extern char tilsprite, palsprite;
 
+/* A 32×32 BG tilemap (one screen), all pointing at tile 0 = the diamond.
+ * SNES map entries are 16-bit (tile# + palette/priority/flip bits); 0x0000
+ * = tile 0, palette 0, no flip. 32*32 = 1024 entries = 2048 bytes. We fill
+ * it at runtime so the source stays small. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
     u16 x = 120, y = 100;
+    u16 i;
 
-    /* BG_MODE1 with all BG layers disabled — we render only the
-     * sprite layer on top of the backdrop colour. */
+    /* BG_MODE1: BG0/BG1 are 16-colour, BG2 is 4-colour — standard mix.
+     * We use BG0 for the wallpaper and the sprite layer on top. */
     setMode(BG_MODE1, 0);
-    bgSetDisable(0);
     bgSetDisable(1);
     bgSetDisable(2);
 
-    /* Backdrop colour (CGRAM entry 0). RGB5: red=0, green=0, blue=15
-     * → bright SNES blue. setPaletteColor packs to BGR555 for us. */
-    setPaletteColor(0, RGB5(0, 0, 15));
+    /* Load the diamond tile + its palette as BG0's tileset. Tile gfx go to
+     * VRAM $2000, palette into BG palette 0. 32 bytes of tile (one 8×8 4bpp
+     * tile), 32 bytes of palette (16 colours × 2). */
+    bgInitTileSet(0, (u8 *)&tilsprite, (u8 *)&palsprite,
+                  0,            /* palette entry 0 */
+                  32,           /* tile data size  */
+                  32,           /* palette size    */
+                  BG_16COLORS,  /* colour mode     */
+                  0x2000);      /* VRAM addr for BG0 tiles */
+
+    /* Fill the map with tile 0 and upload it to VRAM $6000. */
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0000;
+    bgInitMapSet(0, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x6000);
+
+    bgSetEnable(0);
 
-    /* Upload 32 bytes of sprite tile + 32 bytes of sprite palette to
-     * VRAM $0000 / OBJ palette slot 0. OBJ_SIZE8_L16 = small sprites
-     * are 8×8, large 16×16 (we use small). */
+    /* Upload the same tile as a sprite (VRAM $0000, OBJ palette slot 0) so
+     * the movable sprite reads distinctly on top of the wallpaper. */
     oamInitGfxSet(&tilsprite, 32, &palsprite, 32,
                   0,              /* OBJ palette slot */
                   0x0000,         /* VRAM address for sprite tiles */
                   OBJ_SIZE8_L16);
 
-    /* Place sprite #0 at the centre. */
+    /* Place sprite #0 at the centre, highest priority so it sits over BG0. */
     oamSet(0, x, y,
-           3 /* highest priority */,
-           0 /* no flip */, 0 /* palette */, 0 /* tile index */, 0 /* objsize */);
+           3 /* priority */, 0 /* no flip */, 0 /* palette */,
+           0 /* tile index */, 0 /* objsize */);
     oamSetEx(0, OBJ_SMALL, OBJ_SHOW);
 
-    /* Until setScreenOn() fires, the SNES holds forced blank
-     * (INIDISP $80) and nothing renders. */
+    /* Until setScreenOn() fires, the SNES holds forced blank (INIDISP $80)
+     * and nothing renders. */
     setScreenOn();
 
     while (1) {

package/examples/snes/templates/platformer-data.asm

@@ -322,4 +322,26 @@ palsprite:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00, $00, $00, $00, $00, $00, $00
 
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; playfield never reads as a flat/blank backdrop. Quadrant->colour: TL=1,
+; TR=2, BL=3, BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1
+; pairs, bytes 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/platformer.c

@@ -23,11 +23,16 @@
 
 extern char tilfont, palfont;
 extern char tilsprite, palsprite;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * No public prototype in console.h, so declare it; call once per frame. */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * playfield reads as a real backdrop, not flat blank. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 typedef struct { s16 x, y, w, h; } Rect;
 
 #define WORLD_W  512
@@ -80,7 +85,17 @@ int main(void) {
      * registers — point BG0 at the same font ($3000) + map ($6800). */
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the playfield never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of sprites $0000 and
+     * the console gfx $3000 / map $6800). Map entries use palette block 1
+     * (0x0400) so the wallpaper palette doesn't disturb the console font
+     * palette in block 0 (HUD text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     oamInitGfxSet(&tilsprite, 32, &palsprite, 32, 0, 0x0000, OBJ_SIZE8_L16);

package/examples/snes/templates/puzzle-data.asm

@@ -309,4 +309,26 @@ palfont:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00
 
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; playfield never reads as a flat/blank backdrop. Quadrant->colour: TL=1,
+; TR=2, BL=3, BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1
+; pairs, bytes 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/puzzle.c

@@ -15,11 +15,16 @@
 #include "snes_sfx.c"
 
 extern char tilfont, palfont;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * No public prototype in console.h, so declare it; call once per frame. */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * playfield reads as a real backdrop, not flat blank. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 #define COLS 6
 #define ROWS 12
 
@@ -136,6 +141,7 @@ static void render_score(void) {
 int main(void) {
     s16 r, c;
     u16 pad, prev = 0, fall_rate;
+    u16 i;
     u8 t;
 
     consoleSetTextMapPtr(0x6800);
@@ -147,7 +153,17 @@ int main(void) {
      * registers — point BG0 at the same font ($3000) + map ($6800). */
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the playfield never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of sprites $0000 and
+     * the console gfx $3000 / map $6800). Map entries use palette block 1
+     * (0x0400) so the wallpaper palette doesn't disturb the console font
+     * palette in block 0 (HUD/grid text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     for (r = 0; r < ROWS; r++)

package/examples/snes/templates/racing-data.asm

@@ -328,4 +328,26 @@ palsprite:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00, $00, $00, $00, $00, $00, $00
 
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; playfield never reads as a flat/blank backdrop. Quadrant->colour: TL=1,
+; TR=2, BL=3, BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1
+; pairs, bytes 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/racing.c

@@ -12,11 +12,16 @@
 
 extern char tilfont, palfont;
 extern char tilsprite, palsprite;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * No public prototype in console.h, so declare it; call once per frame. */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * playfield reads as a real backdrop, not flat blank. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 #define LANE_LEFT_X    72
 #define LANE_MID_X    124
 #define LANE_RIGHT_X  176
@@ -103,6 +108,7 @@ static void draw_road(void) {
 int main(void) {
     u16 pad;
     u8 i;
+    u16 bi;
     s16 step;
 
     consoleSetTextMapPtr(0x6800);
@@ -114,7 +120,17 @@ int main(void) {
      * registers — point BG0 at the same font ($3000) + map ($6800). */
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the playfield never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of sprites $0000 and
+     * the console gfx $3000 / map $6800). Map entries use palette block 1
+     * (0x0400) so the wallpaper palette doesn't disturb the console font
+     * palette in block 0 (HUD/road text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (bi = 0; bi < 32 * 32; bi++) bg_map[bi] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     /* 2 sprite tiles × 32 bytes = 64 bytes */

package/examples/snes/templates/shmup-data.asm

@@ -351,4 +351,26 @@ palsprite:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00, $00, $00, $00, $00, $00, $00
 
+; ── Background wallpaper (one 8×8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; playfield never reads as a flat/blank backdrop. Quadrant→colour: TL=1,
+; TR=2, BL=3, BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1
+; pairs, bytes 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends