romdevtools 0.16.0 → 0.22.0

package/examples/pce/sports/main.c

@@ -0,0 +1,254 @@
+/*
+ * PC Engine "sports" — a Pong-style two-paddle scaffold.
+ *
+ * Two paddles and a bouncing ball on a netted court. The d-pad moves player 1's
+ * (left) paddle up/down. Player 2's (right) paddle follows the ball with a
+ * chase-AI so the game is playable solo. The ball deflects off paddles and the
+ * top/bottom court lines; a ball past either edge scores for the other side and
+ * re-serves. Score is shown with background digit tiles. Mirrors the
+ * NES/Genesis/SNES/GB/SMS sports scaffolds.
+ *
+ * Paddles + ball are hardware sprites; the court (green field, white border
+ * lines, dashed centre net) is the BG tilemap, so the screen is clearly a
+ * sports court (clears the verify gate).
+ *
+ * PCE notes (see pce_hw.h / MENTAL_MODEL.md):
+ *   - disp_enable() turns on BG + sprites + the VBlank IRQ (waitvsync needs it).
+ *   - .bss must be non-empty (pce_video.c's _pce_keep[] covers it).
+ *
+ * cc65 is C89 — declare locals at the top of a block.
+ */
+#include <pce.h>
+#include <stdint.h>   /* int8_t/int16_t for ball velocity + positions         */
+#include "pce_hw.h"
+
+/* ---- VRAM layout (word addresses) --------------------------------------- */
+#define BAT_VRAM     0x0000
+#define FONT_VRAM    0x1000   /* digit tiles                                 */
+#define GREEN_VRAM   0x1400   /* court field (colour 1)                      */
+#define LINE_VRAM    0x1410   /* court line / border (colour 2)             */
+#define NET_VRAM     0x1420   /* dashed centre net                         */
+#define PADDLE_VRAM  0x1800   /* 16x16 paddle segment                       */
+#define BALL_VRAM    0x1840   /* 16x16 ball                                  */
+
+#define BAT_ENTRY(pal, vram)  ((u16)(((pal) << 12) | ((vram) >> 4)))
+
+#define COURT_TOP   24
+#define COURT_BOT   216
+#define PADDLE_H    48          /* 3 stacked 16px sprite segments             */
+#define BALL_SIZE   12
+#define PADDLE_X1   16
+#define PADDLE_X2   224
+
+/* ---- font (digits only) ------------------------------------------------- */
+#define NUM_GLYPHS 10
+static const u8 FONT5x7[NUM_GLYPHS][7] = {
+    {0x0E,0x11,0x13,0x15,0x19,0x11,0x0E}, /* 0 */
+    {0x04,0x0C,0x04,0x04,0x04,0x04,0x0E}, /* 1 */
+    {0x0E,0x11,0x01,0x02,0x04,0x08,0x1F}, /* 2 */
+    {0x1F,0x02,0x04,0x02,0x01,0x11,0x0E}, /* 3 */
+    {0x02,0x06,0x0A,0x12,0x1F,0x02,0x02}, /* 4 */
+    {0x1F,0x10,0x1E,0x01,0x01,0x11,0x0E}, /* 5 */
+    {0x06,0x08,0x10,0x1E,0x11,0x11,0x0E}, /* 6 */
+    {0x1F,0x01,0x02,0x04,0x08,0x08,0x08}, /* 7 */
+    {0x0E,0x11,0x11,0x0E,0x11,0x11,0x0E}, /* 8 */
+    {0x0E,0x11,0x11,0x0F,0x01,0x02,0x0C}  /* 9 */
+};
+
+/* ---- state -------------------------------------------------------------- */
+static int16_t p1y, p2y, bx, by;
+static int8_t  bdx, bdy;
+static u8  score_p1, score_p2;
+static u8  serve_timer;
+static u8  pad;
+static u16 tile_buf[16];
+static u16 spr_buf[64];
+static u8  sfx_timer;
+
+static void make_solid_tile(u16 *t, u8 ci) {
+    u8 r;
+    u8 p0 = (ci & 1) ? 0xFF : 0x00;
+    u8 p1 = (ci & 2) ? 0xFF : 0x00;
+    u8 p2 = (ci & 4) ? 0xFF : 0x00;
+    u8 p3 = (ci & 8) ? 0xFF : 0x00;
+    for (r = 0; r < 8; ++r) {
+        t[r]     = (u16)(p0 | (p1 << 8));
+        t[r + 8] = (u16)(p2 | (p3 << 8));
+    }
+}
+
+/* net tile: green field (colour 1) with a colour-2 vertical dash centre column */
+static void make_net_tile(u16 *t) {
+    u8 r;
+    for (r = 0; r < 8; ++r) {
+        u8 dash = (r < 5);   /* dashed: top 5 rows of each tile are the dash  */
+        u8 p1 = dash ? 0x18 : 0x00;  /* centre 2 px -> colour 2 (plane1)       */
+        t[r]     = (u16)(0x00FF | (p1 << 8));  /* plane0 full (green) + dash   */
+        t[r + 8] = 0x0000;
+    }
+}
+
+static void make_paddle_sprite(void) {
+    u8 r;
+    for (r = 0; r < 64; ++r) spr_buf[r] = 0;
+    /* a solid 8px-wide vertical bar centred in the 16px cell, colour 1 */
+    for (r = 0; r < 16; ++r) spr_buf[r] = 0x0FF0;
+    load_tiles(PADDLE_VRAM, spr_buf, 64);
+}
+
+static void make_ball_sprite(void) {
+    static const u16 ball[16] = {
+        0x0000, 0x0000, 0x07E0, 0x0FF0, 0x1FF8, 0x1FF8, 0x3FFC, 0x3FFC,
+        0x3FFC, 0x3FFC, 0x1FF8, 0x1FF8, 0x0FF0, 0x07E0, 0x0000, 0x0000
+    };
+    u8 r;
+    for (r = 0; r < 64; ++r) spr_buf[r] = 0;
+    for (r = 0; r < 16; ++r) spr_buf[r] = ball[r];   /* colour 1 */
+    load_tiles(BALL_VRAM, spr_buf, 64);
+}
+
+static void upload_font(void) {
+    u8 g, row, bits, plane0;
+    for (g = 0; g < NUM_GLYPHS; ++g) {
+        for (row = 0; row < 16; ++row) tile_buf[row] = 0;
+        for (row = 0; row < 7; ++row) {
+            bits = FONT5x7[g][row];
+            plane0 = 0;
+            if (bits & 0x10) plane0 |= 0x40;
+            if (bits & 0x08) plane0 |= 0x20;
+            if (bits & 0x04) plane0 |= 0x10;
+            if (bits & 0x02) plane0 |= 0x08;
+            if (bits & 0x01) plane0 |= 0x04;
+            tile_buf[row] = (u16)plane0;
+        }
+        load_tiles((u16)(FONT_VRAM + g * 16), tile_buf, 16);
+    }
+}
+
+static void draw_court(void) {
+    u8 r, c;
+    u16 g  = BAT_ENTRY(0, GREEN_VRAM);
+    u16 ln = BAT_ENTRY(0, LINE_VRAM);
+    u16 nt = BAT_ENTRY(0, NET_VRAM);
+    u16 e;
+    for (r = 0; r < 32; ++r) {
+        vram_set_write_addr((u16)(BAT_VRAM + r * 32));
+        for (c = 0; c < 32; ++c) {
+            if (r <= 2 || r >= 27)       e = ln;   /* top/bottom border       */
+            else if (c == 1 || c == 30)  e = ln;   /* sidelines               */
+            else if (c == 16)            e = nt;   /* centre net              */
+            else                          e = g;    /* field                   */
+            VDC_DATA_LO = (u8)(e & 0xFF);
+            VDC_DATA_HI = (u8)(e >> 8);
+        }
+    }
+}
+
+static void put_glyph(u8 col, u8 row, u8 digit) {
+    u16 e = BAT_ENTRY(0, (u16)(FONT_VRAM + digit * 16));
+    vram_set_write_addr((u16)(BAT_VRAM + row * 32 + col));
+    VDC_DATA_LO = (u8)(e & 0xFF);
+    VDC_DATA_HI = (u8)(e >> 8);
+}
+
+static void draw_scores(void) {
+    put_glyph(12, 1, (u8)(score_p1 % 10));
+    put_glyph(19, 1, (u8)(score_p2 % 10));
+}
+
+static void serve_ball(u8 to_left) {
+    bx = 120; by = 110;
+    bdx = to_left ? -2 : 2;
+    bdy = ((score_p1 + score_p2) & 1) ? -1 : 1;
+    serve_timer = 40;
+}
+
+void main(void) {
+    u8 i;
+
+    _pce_keep[0] = 0;
+
+    /* palette */
+    vce_set_color(0,   PCE_RGB(0, 1, 0));   /* backdrop dark green          */
+    vce_set_color(1,   PCE_RGB(0, 4, 1));   /* BG c1: court green           */
+    vce_set_color(2,   PCE_RGB(7, 7, 7));   /* BG c2: white lines/net/digit */
+    vce_set_color(256, PCE_RGB(0, 0, 0));   /* spr pal0 transparent         */
+    vce_set_color(257, PCE_RGB(7, 7, 7));   /* spr pal0 c1: white paddle    */
+    vce_set_color(272, PCE_RGB(0, 0, 0));   /* spr pal1 transparent         */
+    vce_set_color(273, PCE_RGB(7, 7, 0));   /* spr pal1 c1: yellow ball     */
+
+    upload_font();
+    make_solid_tile(tile_buf, 1); load_tiles(GREEN_VRAM, tile_buf, 16);
+    make_solid_tile(tile_buf, 2); load_tiles(LINE_VRAM, tile_buf, 16);
+    make_net_tile(tile_buf);      load_tiles(NET_VRAM, tile_buf, 16);
+    make_paddle_sprite();
+    make_ball_sprite();
+
+    draw_court();
+
+    p1y = 90; p2y = 90;
+    score_p1 = 0; score_p2 = 0;
+    sfx_timer = 0;
+    serve_ball(0);
+    draw_scores();
+
+    pce_joy_init();
+    disp_enable();
+
+    for (;;) {
+        u8 slot;
+        int16_t target;
+        waitvsync();
+
+        /* stage sprites: P1 paddle (3 segs), P2 paddle (3 segs), ball */
+        slot = 0;
+        for (i = 0; i < 3; ++i)
+            set_sprite(slot++, PADDLE_X1, (u16)(p1y + i * 16), PADDLE_VRAM >> 6, 0);
+        for (i = 0; i < 3; ++i)
+            set_sprite(slot++, PADDLE_X2, (u16)(p2y + i * 16), PADDLE_VRAM >> 6, 0);
+        set_sprite(slot++, (u16)bx, (u16)by, BALL_VRAM >> 6, 1);
+        satb_dma();
+
+        pad = pce_joy_read();
+
+        /* P1 control */
+        if ((pad & PCE_JOY_UP)   && p1y > COURT_TOP)            p1y -= 3;
+        if ((pad & PCE_JOY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 3;
+
+        /* P2 chase-AI */
+        target = (int16_t)(by - PADDLE_H / 2 + BALL_SIZE / 2);
+        if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+        else if (p2y > target && p2y > COURT_TOP)       p2y -= 2;
+
+        if (serve_timer > 0) {
+            serve_timer--;
+        } else {
+            bx = (int16_t)(bx + bdx);
+            by = (int16_t)(by + bdy);
+
+            if (by < COURT_TOP) { by = COURT_TOP; bdy = (int8_t)(-bdy); psg_tone(1, 0x280, 18); sfx_timer = 4; }
+            if (by + BALL_SIZE > COURT_BOT) { by = (int16_t)(COURT_BOT - BALL_SIZE); bdy = (int8_t)(-bdy); psg_tone(1, 0x280, 18); sfx_timer = 4; }
+
+            /* left paddle */
+            if (bdx < 0 && bx <= PADDLE_X1 + 12 && bx + BALL_SIZE >= PADDLE_X1 &&
+                by + BALL_SIZE > p1y && by < p1y + PADDLE_H) {
+                bdx = (int8_t)(-bdx);
+                bx = PADDLE_X1 + 12;
+                psg_tone(0, 0x200, 22); sfx_timer = 4;
+            }
+            /* right paddle */
+            if (bdx > 0 && bx + BALL_SIZE >= PADDLE_X2 && bx <= PADDLE_X2 + 12 &&
+                by + BALL_SIZE > p2y && by < p2y + PADDLE_H) {
+                bdx = (int8_t)(-bdx);
+                bx = (int16_t)(PADDLE_X2 - BALL_SIZE);
+                psg_tone(0, 0x200, 22); sfx_timer = 4;
+            }
+
+            /* scoring */
+            if (bx < 2)   { if (score_p2 < 9) score_p2++; draw_scores(); psg_tone(0, 0x100, 24); sfx_timer = 8; serve_ball(0); }
+            if (bx > 246) { if (score_p1 < 9) score_p1++; draw_scores(); psg_tone(0, 0x100, 24); sfx_timer = 8; serve_ball(1); }
+        }
+
+        if (sfx_timer) { --sfx_timer; if (sfx_timer == 0) { psg_off(0); psg_off(1); } }
+    }
+}

package/examples/pce/sprite_move/main.c

@@ -90,7 +90,10 @@ static void make_sprite(void) {
 }
 
 /* Draw a 32x32-cell checkerboard of TILE_A / TILE_B across the BAT. The default
- * PCE virtual screen is 32x32 cells (256x256 px), which covers the display. */
+ * PCE virtual screen is 32x32 cells (256x256 px), which covers the display.
+ * A two-colour checkerboard (green + dark teal) makes the whole playfield read
+ * as a real, visible background — a SOLID single-colour fill instead looks blank
+ * to a human (one colour covers >92% of the screen), so we alternate by cell. */
 static void fill_bat(void) {
     u16 ea = BAT_ENTRY(TILE_A_VRAM, 0);
     u16 eb = BAT_ENTRY(TILE_B_VRAM, 0);
@@ -98,7 +101,9 @@ static void fill_bat(void) {
     for (r = 0; r < 32; ++r) {
         vram_set_write_addr((u16)(BAT_VRAM + r * 32));
         for (col = 0; col < 32; ++col) {
-            e = ea;     /* solid background so the sprite stands out */
+            /* 2x2-cell checkerboard: alternates green/teal so the background is
+             * unmistakably present while the sprite still stands out clearly. */
+            e = (((r >> 1) ^ (col >> 1)) & 1) ? eb : ea;
             VDC_DATA_LO = (u8)(e & 0xFF);
             VDC_DATA_HI = (u8)(e >> 8);
         }

package/examples/sms/main.c

@@ -47,9 +47,10 @@ static void vdp_init(void) {
 }
 
 /* ─── Palette + tile data ─────────────────────────────────────────── */
-/* SMS CRAM: 2-2-2 BGR. Entry 0 = backdrop. */
+/* SMS CRAM: 2-2-2 BGR. Entry 0 = backdrop. Entries: 1 = yellow 'H',
+ * 2 = blue panel, 3 = dark-blue panel (the checkerboard fill colours). */
 static const uint8_t palette[32] = {
-  0x30, 0x0F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,   /* BG: blue, yellow */
+  0x10, 0x0F, 0x30, 0x14, 0x00, 0x00, 0x00, 0x00,   /* BG: backdrop, yellow, blue, dk-blue */
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,   /* sprite palette unused */
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
@@ -68,6 +69,23 @@ static const uint8_t tile_h[32] = {
   0x00, 0x00, 0x00, 0x00,
 };
 
+/* Tile 2 = solid colour 2 (blue), tile 3 = solid colour 3 (dark blue).
+ * The whole 32×24 screen is painted as a 2-colour checkerboard so the
+ * screen is obviously not blank and no single colour dominates. Plane 1
+ * set → colour 2; planes 0+1 set → colour 3. */
+static const uint8_t tile_fill2[32] = {
+  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,
+};
+static const uint8_t tile_fill3[32] = {
+  0xFF, 0xFF, 0x00, 0x00,  0xFF, 0xFF, 0x00, 0x00,
+  0xFF, 0xFF, 0x00, 0x00,  0xFF, 0xFF, 0x00, 0x00,
+  0xFF, 0xFF, 0x00, 0x00,  0xFF, 0xFF, 0x00, 0x00,
+  0xFF, 0xFF, 0x00, 0x00,  0xFF, 0xFF, 0x00, 0x00,
+};
+
 /* ─── Upload helpers ──────────────────────────────────────────────── */
 static void load_palette(void) {
   uint8_t i;
@@ -77,16 +95,27 @@ static void load_palette(void) {
 
 static void load_tile(void) {
   uint8_t i;
-  /* Tile 1 at VRAM offset 32 (= tile_idx * 32). Tile 0 left blank. */
+  /* Tile 1 = 'H' at VRAM offset 32 (= tile_idx * 32). Tile 0 left blank. */
   vdp_set_addr(32, VDP_VRAM_WRITE);
   for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_h[i];
+  /* Tile 2 = blue fill (offset 64), tile 3 = dark-blue fill (offset 96). */
+  vdp_set_addr(64, VDP_VRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_fill2[i];
+  vdp_set_addr(96, VDP_VRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_fill3[i];
 }
 
+/* Paint the whole 32×24 visible screen as a blue/dark-blue checkerboard so
+ * the screen is obviously not blank and no single colour dominates. */
 static void clear_name_table(void) {
-  uint16_t i;
+  uint8_t row, col;
   vdp_set_addr(0x3800, VDP_VRAM_WRITE);
-  /* 32 cols × 28 rows × 2 bytes = 1792 entries. */
-  for (i = 0; i < 1792; i++) PORT_VDP_DATA = 0;
+  for (row = 0; row < 24; row++) {
+    for (col = 0; col < 32; col++) {
+      PORT_VDP_DATA = ((row ^ col) & 1) ? 2 : 3;   /* checkerboard tiles 2/3 */
+      PORT_VDP_DATA = 0;                            /* attr: BG palette, no flip */
+    }
+  }
 }
 
 static void place_h(void) {

package/examples/sms/templates/hello_sprite.c

@@ -28,22 +28,37 @@ extern void sms_vdp_write_reg(uint8_t reg, uint8_t value);
 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);
 extern void sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
 extern void sms_sat_upload(void);
 
-/* BG palette: backdrop blue + yellow. Sprite palette (entries 16-31)
- * we set white at index 17 so our sprite is visible.
+/* BG palette: backdrop blue, colour 1 = teal, colour 2 = navy (the two
+ * tones of the dithered BG). Sprite palette (entries 16-31) sets white at
+ * index 17 so our sprite is visible.
  * SMS CRAM is 2-2-2 BGR: 0x00=black, 0x3F=white. */
 static const uint8_t palette[32] = {
-  0x10,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x10,0x38,0x20,0x00, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   0x00,0x3F,0x00,0x00, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
 };
 
+/* Two BG tiles in the BG bank at $0000. Tile 0 is a dithered checkerboard
+ * (plane0/plane1 alternate per row) so the whole BG fills with TWO colours
+ * and no single colour dominates the frame — a flat one-colour fill still
+ * reads as a blank screen. */
+static const uint8_t bg_tiles[32 * 1] = {
+  /* T_BG — dither: plane0=0xAA→colour 1, plane1=0x55→colour 2, swapped
+   * each row so it reads as a fine checkerboard. */
+  0xAA,0x55,0x00,0x00, 0x55,0xAA,0x00,0x00,
+  0xAA,0x55,0x00,0x00, 0x55,0xAA,0x00,0x00,
+  0xAA,0x55,0x00,0x00, 0x55,0xAA,0x00,0x00,
+  0xAA,0x55,0x00,0x00, 0x55,0xAA,0x00,0x00,
+};
+
 /* One 8×8 sprite tile (4bpp interleaved). Filled square in color 1. */
 static const uint8_t sprite_tile[32] = {
   0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
@@ -52,6 +67,14 @@ static const uint8_t sprite_tile[32] = {
   0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
 };
 
+/* Fill the whole 32×28 name table with the dithered BG tile. */
+static void draw_bg(void) {
+  uint8_t row, col;
+  for (row = 0; row < 28; row++)
+    for (col = 0; col < 32; col++)
+      sms_set_tilemap_cell(row, col, 0, 0);
+}
+
 void main(void) {
   uint8_t x = 124;   /* mid-screen X */
   uint8_t y = 88;    /* mid-screen Y */
@@ -59,6 +82,9 @@ void main(void) {
 
   sms_vdp_init();
   sms_load_palette(palette);
+  /* BG dither tile → BG bank $0000, then paint the whole name table. */
+  sms_load_tiles(0x0000, bg_tiles, 32);
+  draw_bg();
   /* Upload one sprite tile to VRAM $2000 (sprite tile area). */
   sms_load_tiles(0x2000, sprite_tile, 32);
 

package/examples/sms/templates/music_demo.c

@@ -29,10 +29,11 @@ extern void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte
 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);
 
-/* BG palette: backdrop dark blue, fg colour 1 = bright cyan, colour 2 = yellow.
- * SMS CRAM is 2-2-2 BGR — 0x30 = bright blue, 0x3F = white, 0x0F = yellow. */
+/* BG palette: backdrop dark blue, fg colour 1 = bright cyan, colour 2 = yellow,
+ * colour 3 = navy (the second dither tone behind the text).
+ * SMS CRAM is 2-2-2 BGR — 0x20 = blue, 0x3F = white/cyan, 0x0F = yellow. */
 static const uint8_t palette[32] = {
-  0x20, 0x3F, 0x0F, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x20, 0x3F, 0x0F, 0x28, 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, 0x00, 0x00,
@@ -100,8 +101,19 @@ static const uint8_t font_tiles[] = {
   0xC3,0x00,0x00,0x00, 0xC3,0x00,0x00,0x00,
   0xC3,0x00,0x00,0x00, 0xC3,0x00,0x00,0x00,
   0x66,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+
+  /* tile 9 — dithered BG. plane1=0xFF (colour-2 bit always on), plane0
+   * alternates 0xAA/0x55 so pixels flip between colour 2 (yellow) and
+   * colour 3 (navy). Fills the whole field with TWO tones so no single
+   * colour dominates, while the cyan (colour 1) text stays distinct. */
+  0xAA,0xFF,0x00,0x00, 0x55,0xFF,0x00,0x00,
+  0xAA,0xFF,0x00,0x00, 0x55,0xFF,0x00,0x00,
+  0xAA,0xFF,0x00,0x00, 0x55,0xFF,0x00,0x00,
+  0xAA,0xFF,0x00,0x00, 0x55,0xFF,0x00,0x00,
 };
 
+#define T_DITHER 9
+
 /* Tile indices for each char in our message — 'S' 'M' 'S' ' ' 'M' 'U'
  * 'S' 'I' 'C' ' ' 'D' 'E' 'M' 'O'. 14 cells total. */
 static const uint8_t message[14] = {
@@ -114,9 +126,11 @@ static const uint8_t message[14] = {
 static void clear_name_table(void) {
   uint8_t row;
   uint8_t col;
+  /* Fill with the dithered BG tile (not blank) so the whole screen reads
+   * as a two-tone field and never as a blank backdrop. */
   for (row = 0; row < 28; row++) {
     for (col = 0; col < 32; col++) {
-      sms_set_tilemap_cell(row, col, 0, 0);
+      sms_set_tilemap_cell(row, col, T_DITHER, 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();