romdevtools 0.16.0 → 0.22.0

package/examples/nes/templates/music_demo.c

@@ -43,6 +43,37 @@ extern const unsigned char music_data[];
 
 static const unsigned char bg_colors[4] = { 0x0F, 0x01, 0x21, 0x31 };
 
+/* Two BG tiles so the backdrop isn't a single flat colour (a uniform
+ * screen reads >=92% one colour and fails the blank-screen check):
+ *   tile 1 — solid colour 1
+ *   tile 2 — solid colour 2
+ * We checkerboard them across the nametable below. NES BG fetches from
+ * $1000-$1FFF under the default PPUCTRL (bit 4 set), so BG tiles upload
+ * there. */
+static const unsigned char bg_tiles[2 * 16] = {
+  /* tile 1: solid colour 1 (plane 0 all set, plane 1 clear) */
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  /* tile 2: solid colour 2 (plane 1 all set, plane 0 clear) */
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+};
+
+/* Fill nametable 0 ($2000) with a checkerboard of tiles 1 and 2 so the
+ * screen shows two distinct colours. Attribute table left at palette 0.
+ * Caller must have the PPU off. */
+static void fill_bg(void) {
+  unsigned int addr;
+  unsigned char y, x;
+  for (y = 0; y < 30; y++) {
+    addr = 0x2000 + (unsigned int)y * 32;
+    for (x = 0; x < 32; x++) {
+      vram_unsafe_set(addr, (unsigned char)(((x ^ y) & 1) + 1));
+      ++addr;
+    }
+  }
+}
+
 void main(void) {
   unsigned char palette[32];
   unsigned char i;
@@ -50,9 +81,18 @@ void main(void) {
   unsigned char frame = 0;
 
   for (i = 0; i < 32; i++) palette[i] = bg_colors[0];
+  /* BG palette 0: backdrop black, colour 1 blue, colour 2 red — gives the
+   * checkerboard two visibly different cells. */
+  palette[0] = 0x0F;   /* $3F00 backdrop */
+  palette[1] = 0x11;   /* colour 1 — blue */
+  palette[2] = 0x16;   /* colour 2 — red  */
 
   ppu_off();
   palette_load(palette);
+  /* Upload the two BG tiles to the BG pattern table at $1000. */
+  chr_ram_upload(0x1000, bg_tiles, sizeof(bg_tiles));
+  /* Paint the checkerboard backdrop so the screen is visibly NOT blank. */
+  fill_bg();
   oam_clear();
 
   /* Start the music BEFORE rendering — FamiToneInit takes a few

package/examples/nes/templates/platformer.c

@@ -28,7 +28,7 @@
 
 #include "nes_runtime.h"
 
-/* ── Tiles: player idle/jump + platform block ────────────────────── */
+/* ── Tiles: player idle/jump + platform block (SPRITES, table $0000) ── */
 static const uint8_t tile_blank[16] = { 0 };
 static const uint8_t tile_player_idle[16] = {
   0x3C, 0x7E, 0xFF, 0xFF, 0xFF, 0xFF, 0x7E, 0x3C,  /* plane 0 — round blob */
@@ -43,12 +43,46 @@ static const uint8_t tile_platform[16] = {
   0,    0,    0,    0,    0,    0,    0,    0,
 };
 
+/* ── BG scenery tiles (BACKGROUND pattern table $1000) ────────────────
+ * Painted into the nametable so the world reads as a real outdoor scene on
+ * boot (sky + clouds + dirt) instead of sprites floating on flat black. The
+ * BG backdrop colour (palette[0]) is sky blue, so the colours used here are
+ * cloud white (idx1), dirt brown (idx2) and grass green (idx3).
+ *
+ *   BG_CLOUD — a puffy cloud (idx1) dotted across the upper sky.
+ *   BG_DIRT  — solid dirt fill (idx2) for the ground band.
+ *   BG_GRASS — a grass-topped dirt tile (idx3 cap over idx2) for the
+ *              surface row of the ground. */
+#define BG_CLOUD  1   /* BG tile index 1 → uploaded to $1010 */
+#define BG_DIRT   2   /* BG tile index 2 → uploaded to $1020 */
+#define BG_GRASS  3   /* BG tile index 3 → uploaded to $1030 */
+static const uint8_t bg_tile_cloud[16] = {
+  0x00, 0x18, 0x3C, 0x7E, 0x7E, 0x00, 0x00, 0x00,  /* plane 0 → cloud (idx1) */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t bg_tile_dirt[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear  */
+  0xFF, 0xFF, 0xEF, 0xFF, 0xFF, 0xFE, 0xFF, 0xFF,   /* plane 1 → dirt (idx2) */
+};
+static const uint8_t bg_tile_grass[16] = {
+  0xFF, 0xFF, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,  /* plane0: top 2 rows on */
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,  /* plane1: all rows on   */
+};  /* rows 0-1 → both planes = idx3 (grass cap); rows 2-7 → plane1 = idx2 (dirt) */
+
 static const uint8_t palette[32] = {
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x21, 0x32, 0x30,  /* sp0: player — blue */
+  /* BG0: sky-blue backdrop, cloud white (idx1), dirt brown (idx2),
+   * grass green (idx3) */
+  0x21, 0x30, 0x17, 0x2A,
+  0x21, 0x30, 0x17, 0x2A,
+  0x21, 0x30, 0x17, 0x2A,
+  0x21, 0x30, 0x17, 0x2A,
+  /* The universal backdrop ($3F00) is MIRRORED at $3F10 — the sprite
+   * palette-0 colour-0 slot. palette_load writes all 32 bytes in order, so
+   * byte 16 (this slot) is the LAST write to that mirror and therefore wins.
+   * Keep it equal to the BG backdrop (sky blue) or the sky renders as
+   * whatever colour-0 you put here, not the BG[0] above. (Sprite colour 0 is
+   * transparent regardless, so this never affects how sprites draw.) */
+  0x21, 0x21, 0x32, 0x30,  /* sp0: player — blue (colour 0 = backdrop mirror) */
   0x0F, 0x18, 0x28, 0x38,  /* sp1: platforms — green */
   0x0F, 0x16, 0x06, 0x36,
   0x0F, 0x2A, 0x1A, 0x0A,
@@ -102,8 +136,33 @@ void main(void) {
   chr_ram_upload(0x0020, tile_player_jump,  16);
   chr_ram_upload(0x0030, tile_platform,     16);
 
+  /* BG scenery tiles go in pattern table 1 ($1000) — where the default
+   * PPUCTRL points the background fetch. */
+  chr_ram_upload(0x1010, bg_tile_cloud, 16);
+  chr_ram_upload(0x1020, bg_tile_dirt,  16);
+  chr_ram_upload(0x1030, bg_tile_grass, 16);
+
   palette_load(palette);
 
+  /* Paint the outdoor scene into the nametable while rendering is off
+   * (vram_unsafe_set = raw write; tile_set's NMI queue would deadlock before
+   * ppu_on). Sky-blue backdrop shows through the empty upper rows; we dot
+   * clouds across it, cap the ground with a grass row, and fill the bottom
+   * band with solid dirt. The sprite platforms still draw on top of this. */
+  {
+    uint16_t r, c;
+    /* clouds scattered through the upper sky (rows 2..9) */
+    for (r = 2; r < 10; r++)
+      for (c = (uint16_t)((r * 3) % 6); c < 32; c += 6)
+        vram_unsafe_set((uint16_t)(0x2000 + r * 32 + c), BG_CLOUD);
+    /* grass cap row + solid dirt to the bottom of the screen */
+    for (c = 0; c < 32; c++)
+      vram_unsafe_set((uint16_t)(0x2000 + 24 * 32 + c), BG_GRASS);
+    for (r = 25; r < 30; r++)
+      for (c = 0; c < 32; c++)
+        vram_unsafe_set((uint16_t)(0x2000 + r * 32 + c), BG_DIRT);
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/nes/templates/puzzle.c

@@ -53,12 +53,39 @@ static const uint8_t tile_block_b[16] = {
   0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
   0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
 };
+/* BG scenery tiles — painted into the nametable so the playfield reads as a
+ * real machine on boot (without them the screen is just sprites on flat
+ * black). All live in the BACKGROUND pattern table ($1000); the block tiles
+ * above are sprites ($0000).
+ *
+ *   BG_WALL  — solid bordered block (idx 1, steel blue): the well frame.
+ *   BG_BRICK — a brick/dither pattern (idx 2) tiling the cabinet wall that
+ *              surrounds the well, so the whole screen is covered.
+ *   BG_INNER — a faint grid speck (idx 3) lining the inside of the well so
+ *              empty cells read as a recessed playfield, not a black hole. */
+static const uint8_t tile_wall[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_brick[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear */
+  0xFF, 0x80, 0x80, 0x80, 0xFF, 0x08, 0x08, 0x08,   /* plane 1 → colour 2 brick */
+};
+static const uint8_t tile_inner[16] = {
+  0x88, 0x00, 0x00, 0x00, 0x88, 0x00, 0x00, 0x00,   /* plane 0 specks */
+  0x88, 0x00, 0x00, 0x00, 0x88, 0x00, 0x00, 0x00,   /* plane 1 too → colour 3 */
+};
+#define BG_WALL  1   /* BG tile index 1 → uploaded to $1010 */
+#define BG_BRICK 2   /* BG tile index 2 → uploaded to $1020 */
+#define BG_INNER 3   /* BG tile index 3 → uploaded to $1030 */
 
 static const uint8_t palette[32] = {
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
+  /* BG0: backdrop near-black, wall = steel blue (idx1), brick = brown
+   * (idx2), inner grid = dark grey (idx3). */
+  0x0F, 0x11, 0x17, 0x00,
+  0x0F, 0x11, 0x17, 0x00,
+  0x0F, 0x11, 0x17, 0x00,
+  0x0F, 0x11, 0x17, 0x00,
   /* Sprite palette 0: idx1=red, idx2=green, idx3=blue */
   0x0F, 0x16, 0x1A, 0x12,
   0x0F, 0x16, 0x1A, 0x12,
@@ -156,11 +183,45 @@ void main(void) {
   int8_t  i;
 
   ppu_off();
-  chr_ram_upload(0x0000, tile_blank,    16);
-  chr_ram_upload(0x0010, tile_block_r,  16);
+  chr_ram_upload(0x0000, tile_blank,    16);  /* sprite slot 0 */
+  chr_ram_upload(0x0010, tile_block_r,  16);  /* sprite slots 1..3 */
   chr_ram_upload(0x0020, tile_block_g,  16);
   chr_ram_upload(0x0030, tile_block_b,  16);
+  chr_ram_upload(0x1010, tile_wall,     16);  /* BG slot 1 (background table) */
+  chr_ram_upload(0x1020, tile_brick,    16);  /* BG slot 2 (cabinet wall)     */
+  chr_ram_upload(0x1030, tile_inner,    16);  /* BG slot 3 (well interior)    */
   palette_load(palette);
+
+  /* Draw the cabinet + well into the nametable while rendering is off
+   * (vram_unsafe_set = raw PPU write; the friendly tile_set queue would
+   * deadlock before ppu_on). The grid is 6 wide × 12 tall at pixel origin
+   * (80,16) → tile cols 10..15, rows 2..13; frame it one cell out. We first
+   * tile the WHOLE screen with brick (the machine cabinet), then carve the
+   * recessed well interior, then stamp the steel-blue frame on top — so the
+   * screen is fully covered instead of sprites floating on black. */
+  {
+    uint16_t gx0 = ORIGIN_X / 8, gy0 = ORIGIN_Y / 8;     /* 10, 2  */
+    uint16_t gx1 = gx0 + GRID_W, gy1 = gy0 + GRID_H;     /* 16, 14 (exclusive) */
+    uint16_t cc, rr;
+    /* whole-screen cabinet brick */
+    for (rr = 0; rr < 30; rr++)
+      for (cc = 0; cc < 32; cc++)
+        vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + cc), BG_BRICK);
+    /* recessed well interior (inside the frame) */
+    for (rr = gy0; rr < gy1; rr++)
+      for (cc = gx0; cc < gx1; cc++)
+        vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + cc), BG_INNER);
+    /* steel frame one cell out around the well */
+    for (cc = gx0 - 1; cc <= gx1; cc++) {
+      vram_unsafe_set((uint16_t)(0x2000 + (gy0 - 1) * 32 + cc), BG_WALL); /* top    */
+      vram_unsafe_set((uint16_t)(0x2000 + gy1 * 32 + cc), BG_WALL);       /* bottom */
+    }
+    for (rr = gy0 - 1; rr <= gy1; rr++) {
+      vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + (gx0 - 1)), BG_WALL); /* left   */
+      vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + gx1), BG_WALL);       /* right  */
+    }
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/nes/templates/racing.c

@@ -59,14 +59,22 @@ static const uint8_t tile_digits[10 * 16] = {
 /* ── Background road tiles ───────────────────────────────────────────
  * Default PPUCTRL ($90) reads BG patterns from pattern table 1 ($1000),
  * so these go to CHR $1000+ and are indexed independently of the sprite
- * tiles above. Colour 1 (white, BG palette 0) draws the markings; the
- * grey backdrop (colour 0) is the road surface.
+ * tiles above. The grey backdrop (colour 0) is the road surface; colour 1
+ * (white) draws the markings, colour 2 (green) the grass, colour 3 the
+ * dark seam in the tarmac.
  *
- * BG_T_EDGE: a solid 2px vertical stripe — the road shoulder line.
- * BG_T_LANE: a 2px vertical dash (on for 4 rows, off for 4) — the
- *            dashed centre lane marking when stacked down a column. */
+ * BG_T_EDGE:  a solid 2px vertical stripe — the road shoulder line.
+ * BG_T_LANE:  a 2px vertical dash (on 4 rows / off 4) — the dashed centre
+ *             lane marking when stacked down a column.
+ * BG_T_GRASS: a textured green roadside (colour 2 hatch) so the area
+ *             outside the shoulders isn't flat — fills the screen sides.
+ * BG_T_ROAD:  a faint tarmac texture (a couple of colour-3 specks) tiled
+ *             across the driving surface so the road doesn't read as one
+ *             solid grey block. */
 #define BG_T_EDGE   1
 #define BG_T_LANE   2
+#define BG_T_GRASS  3
+#define BG_T_ROAD   4
 static const uint8_t bg_tile_edge[16] = {
   0x18, 0x18, 0x18, 0x18, 0x18, 0x18, 0x18, 0x18,   /* plane 0 (colour bit 0) */
   0,    0,    0,    0,    0,    0,    0,    0,
@@ -75,13 +83,21 @@ static const uint8_t bg_tile_lane[16] = {
   0x18, 0x18, 0x18, 0x18, 0x00, 0x00, 0x00, 0x00,   /* dash: 4 on, 4 off */
   0,    0,    0,    0,    0,    0,    0,    0,
 };
+static const uint8_t bg_tile_grass[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear */
+  0xEE, 0xBB, 0xEE, 0xBB, 0xEE, 0xBB, 0xEE, 0xBB,   /* plane 1 → colour 2 hatch */
+};
+static const uint8_t bg_tile_road[16] = {
+  0x00, 0x00, 0x10, 0x00, 0x00, 0x08, 0x00, 0x00,   /* plane 0 specks */
+  0x00, 0x00, 0x10, 0x00, 0x00, 0x08, 0x00, 0x00,   /* plane 1 too → colour 3 */
+};
 
 static const uint8_t palette[32] = {
-  /* BG palettes — light grey backdrop simulates road */
-  0x10, 0x30, 0x16, 0x12,
-  0x10, 0x30, 0x16, 0x12,
-  0x10, 0x30, 0x16, 0x12,
-  0x10, 0x30, 0x16, 0x12,
+  /* BG palettes — light grey backdrop simulates road; idx2 = grass green */
+  0x10, 0x30, 0x1A, 0x00,
+  0x10, 0x30, 0x1A, 0x00,
+  0x10, 0x30, 0x1A, 0x00,
+  0x10, 0x30, 0x1A, 0x00,
   /* Sprite palettes */
   0x10, 0x21, 0x16, 0x30,   /* sp0: blue car (P1) */
   0x10, 0x16, 0x21, 0x30,   /* sp1: red enemy */
@@ -125,8 +141,22 @@ static uint8_t aabb(Car *a, Car *b) {
 #define ROAD_DIV_1     13
 #define ROAD_DIV_2     17
 static void draw_road(void) {
-  uint8_t row;
+  uint8_t row, col;
   uint16_t base;
+  /* Fill the WHOLE nametable so nothing reads as flat colour: grass on the
+   * roadside (outside the shoulders) and a faint tarmac texture on the
+   * driving surface. Then stamp the shoulder + lane markings on top. */
+  for (row = 0; row < 30; row++) {
+    base = (uint16_t)(0x2000 + (uint16_t)row * 32);
+    for (col = 0; col < 32; col++) {
+      if (col < ROAD_EDGE_L || col > ROAD_EDGE_R) {
+        vram_unsafe_set((uint16_t)(base + col), BG_T_GRASS);   /* roadside */
+      } else if (((row + col) & 3) == 0) {
+        vram_unsafe_set((uint16_t)(base + col), BG_T_ROAD);    /* tarmac speck */
+      }
+      /* else leave colour-0 grey road surface */
+    }
+  }
   for (row = ROAD_TOP_ROW; row <= ROAD_BOT_ROW; row++) {
     base = (uint16_t)(0x2000 + (uint16_t)row * 32);
     vram_unsafe_set((uint16_t)(base + ROAD_EDGE_L), BG_T_EDGE);
@@ -183,8 +213,10 @@ void main(void) {
 
   /* BG road tiles live in pattern table 1 ($1000) — that's where the
    * default PPUCTRL ($90) tells the PPU to read background patterns. */
-  chr_ram_upload((uint16_t)(0x1000 + BG_T_EDGE * 16), bg_tile_edge, 16);
-  chr_ram_upload((uint16_t)(0x1000 + BG_T_LANE * 16), bg_tile_lane, 16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_EDGE  * 16), bg_tile_edge,  16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_LANE  * 16), bg_tile_lane,  16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_GRASS * 16), bg_tile_grass, 16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_ROAD  * 16), bg_tile_road,  16);
 
   palette_load(palette);
   draw_road();          /* paint the static road while the PPU is off */

package/examples/nes/templates/shmup.c

@@ -38,10 +38,34 @@ static const uint8_t tile_enemy[16] = {
   0x81, 0x42, 0x24, 0xFF, 0xFF, 0x24, 0x42, 0x81,  /* plane 0 — spider-ish */
   0,    0,    0,    0,    0,    0,    0,    0,
 };
+/* BG starfield tiles — painted across the whole nametable so the screen
+ * reads as a real "space" scene on boot instead of flat black. They live in
+ * the BACKGROUND pattern table ($1000), separate from the sprite tiles above
+ * (the runtime puts BG at $1000, sprites at $0000).
+ *
+ *   BG_DUST  — a faint checkerboard "space dust" that tiles seamlessly; the
+ *              base layer that covers the whole field so it never reads blank.
+ *   BG_STAR  — three small stars (colour 1) sprinkled over the dust.
+ *   BG_BRITE — a single bright + star (colour 2) for the rare close star. */
+static const uint8_t tile_dust[16] = {
+  0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA,  /* plane 0: checker (idx 1) */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_star[16] = {
+  0x00, 0x08, 0x00, 0x42, 0x00, 0x00, 0x20, 0x01,  /* plane 0: four small stars */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_brite[16] = {
+  0x00, 0x00, 0x10, 0x38, 0x10, 0x00, 0x00, 0x00,  /* plane 0: + arms (idx ... ) */
+  0x00, 0x00, 0x10, 0x38, 0x10, 0x00, 0x00, 0x00,  /* plane 1 set too → colour 3 */
+};
+#define BG_DUST  1   /* BG tile index 1 → uploaded to $1010 */
+#define BG_STAR  2   /* BG tile index 2 → uploaded to $1020 */
+#define BG_BRITE 3   /* BG tile index 3 → uploaded to $1030 */
 
 /* ── Palette ─────────────────────────────────────────────────────── */
 static const uint8_t palette[32] = {
-  /* BG (unused but PPU reads $3F00 backdrop) */
+  /* BG0: backdrop near-black, star colour = dim white */
   0x0F, 0x10, 0x20, 0x30,
   0x0F, 0x10, 0x20, 0x30,
   0x0F, 0x10, 0x20, 0x30,
@@ -126,14 +150,39 @@ void main(void) {
 
   ppu_off();
 
-  /* Upload tile data — blank in slot 0 + 3 sprite tiles in slots 1..3. */
+  /* Upload tile data — blank in slot 0 + 3 sprite tiles in slots 1..3,
+   * all in the SPRITE pattern table ($0000). */
   chr_ram_upload(0x0000, tile_blank,  16);
   chr_ram_upload(0x0010, tile_ship,   16);
   chr_ram_upload(0x0020, tile_bullet, 16);
   chr_ram_upload(0x0030, tile_enemy,  16);
+  /* Upload the starfield tiles to the BACKGROUND pattern table
+   * ($1010/$1020/$1030 = BG slots 1/2/3). */
+  chr_ram_upload(0x1010, tile_dust,   16);
+  chr_ram_upload(0x1020, tile_star,   16);
+  chr_ram_upload(0x1030, tile_brite,  16);
 
   palette_load(palette);
 
+  /* Paint a full starfield directly into the nametable while the PPU is off
+   * (vram_unsafe_set = raw write; tile_set's NMI queue would deadlock
+   * before ppu_on). Every one of the 32×30 cells gets the faint "dust" base,
+   * with small stars sprinkled every few cells and the odd bright star — a
+   * deterministic scatter so the backdrop is unambiguously "space", densely
+   * filled rather than flat black. */
+  {
+    uint16_t r, cc;
+    uint8_t tile;
+    for (r = 0; r < 30; r++) {
+      for (cc = 0; cc < 32; cc++) {
+        tile = BG_DUST;                              /* base dust everywhere */
+        if (((r * 5 + cc * 3) % 7) == 0) tile = BG_STAR;   /* sprinkle stars */
+        if (((r * 3 + cc * 7) % 23) == 0) tile = BG_BRITE; /* rare bright one */
+        vram_unsafe_set((uint16_t)(0x2000 + r * 32 + cc), tile);
+      }
+    }
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/nes/templates/sports.c

@@ -34,6 +34,27 @@ static const uint8_t tile_ball[16] = {
   0x00, 0x3C, 0x7E, 0x7E, 0x7E, 0x7E, 0x3C, 0x00,
   0,    0,    0,    0,    0,    0,    0,    0,
 };
+/* BG court tiles (background pattern table $1000), so the court reads as a
+ * real Pong arena on boot instead of sprites on flat black:
+ *   BG_WALL  — solid bar (idx1 white): the top/bottom rails.
+ *   BG_NET   — dashed vertical bar (idx1 white): the centre net.
+ *   BG_FLOOR — a faint court-floor hatch (idx2 green) tiled across the whole
+ *              playfield so the arena surface is covered, not black. */
+static const uint8_t tile_wall[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_net[16] = {
+  0x18, 0x18, 0x00, 0x00, 0x18, 0x18, 0x00, 0x00,  /* dashed vertical bar */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_floor[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear */
+  0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55,   /* plane 1 → colour 2 checker */
+};
+#define BG_WALL  1   /* BG slot 1 → $1010 */
+#define BG_NET   2   /* BG slot 2 → $1020 */
+#define BG_FLOOR 3   /* BG slot 3 → $1030 */
 /* Digits 0-9 (3 wide × 5 tall, padded to 8×8). Used for the score HUD. */
 static const uint8_t tile_digits[10 * 16] = {
   /* 0 */ 0xE0,0xA0,0xA0,0xA0,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
@@ -55,11 +76,12 @@ static const uint8_t tile_digits[10 * 16] = {
 #define T_DIGIT0  3   /* digits live at slots 3..12 */
 
 static const uint8_t palette[32] = {
-  /* BG palettes — only the backdrop matters here */
-  0x0F, 0x30, 0x10, 0x00,
-  0x0F, 0x30, 0x10, 0x00,
-  0x0F, 0x30, 0x10, 0x00,
-  0x0F, 0x30, 0x10, 0x00,
+  /* BG0: backdrop near-black, court walls/net = white (idx1),
+   * court-floor hatch = dark green (idx2) */
+  0x0F, 0x30, 0x1A, 0x00,
+  0x0F, 0x30, 0x1A, 0x00,
+  0x0F, 0x30, 0x1A, 0x00,
+  0x0F, 0x30, 0x1A, 0x00,
   /* Sprite palettes */
   0x0F, 0x30, 0x16, 0x12,  /* sp0: white paddle */
   0x0F, 0x30, 0x16, 0x12,  /* sp1: white ball   */
@@ -103,13 +125,36 @@ void main(void) {
 
   ppu_off();
 
-  /* Upload tiles. */
+  /* Upload sprite tiles (sprite pattern table $0000). */
   chr_ram_upload(T_BLANK   * 16, tile_blank,  16);
   chr_ram_upload(T_PADDLE  * 16, tile_paddle, 16);
   chr_ram_upload(T_BALL    * 16, tile_ball,   16);
   chr_ram_upload(T_DIGIT0  * 16, tile_digits, sizeof(tile_digits));
+  /* Upload court tiles to the BACKGROUND pattern table ($1010..$1030). */
+  chr_ram_upload(0x1010, tile_wall,  16);
+  chr_ram_upload(0x1020, tile_net,   16);
+  chr_ram_upload(0x1030, tile_floor, 16);
 
   palette_load(palette);
+
+  /* Paint the court into the nametable while rendering is off
+   * (vram_unsafe_set = raw write). First carpet the whole playfield with the
+   * green floor hatch so the arena surface is covered, then lay the top/
+   * bottom rails (rows 1 and 27) and the dashed centre net (column 15) on
+   * top. Without the floor the screen is just sprites on flat black. */
+  {
+    uint16_t cc, rr;
+    for (rr = 0; rr < 30; rr++)
+      for (cc = 0; cc < 32; cc++)
+        vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + cc), BG_FLOOR);
+    for (cc = 0; cc < 32; cc++) {
+      vram_unsafe_set((uint16_t)(0x2000 + 1 * 32 + cc),  BG_WALL);  /* top rail (y≈8)   */
+      vram_unsafe_set((uint16_t)(0x2000 + 27 * 32 + cc), BG_WALL);  /* bottom rail(y≈216)*/
+    }
+    for (rr = 2; rr < 27; rr++)
+      vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + 15), BG_NET);   /* centre net       */
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/pce/catch_game/main.c

@@ -27,6 +27,8 @@
 #define BAT_VRAM       0x0000   /* 32x32 background map                       */
 #define FONT_VRAM      0x1000   /* digit + glyph tiles (8x8, 16 words each)   */
 #define BLANK_VRAM     0x1000   /* tile 0 of the font = blank                 */
+#define FIELD_VRAM     0x1700   /* dim "field" BG tile (16 words), drawn behind
+                                 * the HUD so the playfield isn't a blank void  */
 #define CATCHER_VRAM   0x1800   /* catcher sprite cell (16x16 = 64 words)     */
 #define FRUIT_VRAM     0x1840   /* fruit sprite cell (16x16 = 64 words)       */
 
@@ -146,15 +148,30 @@ static void upload_sprites(void) {
     load_tiles(FRUIT_VRAM, fruit_cell, 64);
 }
 
-/* ---- clear the whole BAT to blank tiles --------------------------------- */
+/* ---- build the dim "field" BG tile -------------------------------------- */
+/* A solid 8x8 tile in BG colour index 2 (the dim field blue). Filling the BAT
+ * with this instead of blank gives the playfield a visible background — an
+ * all-blank BAT reads as a near-empty backdrop (one colour > 92% of the screen,
+ * which looks blank to a human). plane1 set = colour index 2. */
+static void upload_field(void) {
+    u16 i;
+    for (i = 0; i < 16; ++i) font_cell[i] = 0;
+    for (i = 0; i < 8; ++i) font_cell[i] = 0xFF00;  /* plane1 (hi byte) = ci 2 */
+    load_tiles(FIELD_VRAM, font_cell, 16);
+}
+
+/* ---- fill the whole BAT with the field tile (a 2x2-cell checkerboard of
+ * field/blank), behind the HUD glyphs which are written on top afterwards ---- */
 static void clear_bat(void) {
     u16 r, c;
+    u16 field = BAT_ENTRY(0, FIELD_VRAM);
     u16 blank = BAT_ENTRY(0, BLANK_VRAM);
     for (r = 0; r < 32; ++r) {
         vram_set_write_addr((u16)(BAT_VRAM + r * 32));
         for (c = 0; c < 32; ++c) {
-            VDC_DATA_LO = (u8)(blank & 0xFF);
-            VDC_DATA_HI = (u8)(blank >> 8);
+            u16 e = (((r >> 1) ^ (c >> 1)) & 1) ? blank : field;
+            VDC_DATA_LO = (u8)(e & 0xFF);
+            VDC_DATA_HI = (u8)(e >> 8);
         }
     }
 }
@@ -229,6 +246,7 @@ void main(void) {
     /* palette: backdrop, BG text colours, sprite colours */
     vce_set_color(0,   PCE_RGB(0, 0, 1));     /* backdrop: near-black blue   */
     vce_set_color(1,   PCE_RGB(7, 7, 7));     /* BG colour 1: white text     */
+    vce_set_color(2,   PCE_RGB(1, 1, 3));     /* BG colour 2: dim field blue */
     vce_set_color(256, PCE_RGB(0, 0, 0));     /* sprite transparent          */
     vce_set_color(257, PCE_RGB(2, 5, 7));     /* sprite c1: cyan (catcher 0) */
     vce_set_color(259, PCE_RGB(2, 5, 7));     /* sprite c3: cyan (catcher)   */
@@ -238,6 +256,7 @@ void main(void) {
 
     upload_font();
     upload_sprites();
+    upload_field();         /* dim field tile for a visible playfield BG       */
 
     clear_bat();
     draw_hud_labels();

package/examples/pce/music_sfx/main.c

@@ -76,6 +76,32 @@ static void draw_bar(u8 active) {
     }
 }
 
+/* Paint a decorative full-screen frame so the demo reads as a real UI panel
+ * instead of a near-empty backdrop. conio only inits a backdrop + font, so an
+ * otherwise text-only screen leaves >92% of pixels one colour, which looks
+ * blank to a human. We fill the top/bottom title bands and both side borders
+ * with a block character (the labels are drawn ON TOP afterwards). PCE conio is
+ * 32 cols x 28 rows. */
+#define SCR_COLS  32
+#define SCR_ROWS  28
+static void draw_frame(void) {
+    u8 x, y;
+    /* solid top band (rows 0-1) and bottom band (rows 26-27) */
+    for (y = 0; y < SCR_ROWS; ++y) {
+        if (y < 2 || y >= SCR_ROWS - 2) {
+            for (x = 0; x < SCR_COLS; ++x) cputcxy(x, y, '#');
+        } else {
+            /* left + right vertical borders (two columns each for weight) */
+            cputcxy(0, y, '#');
+            cputcxy(1, y, '#');
+            cputcxy((u8)(SCR_COLS - 2), y, '#');
+            cputcxy((u8)(SCR_COLS - 1), y, '#');
+        }
+    }
+    /* a mid separator bar under the title so the panel has visible structure */
+    for (x = 2; x < SCR_COLS - 2; ++x) cputcxy(x, 5, '=');
+}
+
 void main(void) {
     u8  pad, prev_pad;
     u8  step;        /* current melody step 0..7              */
@@ -86,8 +112,9 @@ void main(void) {
 
     _keep[0] = 0;
 
-    /* conio: clear + enable display, then paint the static labels. */
+    /* conio: clear + enable display, paint the frame, then the static labels. */
     clrscr();
+    draw_frame();            /* visible bordered panel (not a blank backdrop)  */
     cputsxy(8, 8,  "PC ENGINE MUSIC + SFX");
     cputsxy(8, 11, "MELODY:");
     cputsxy(8, BAR_Y - 1, "STEP:");