romdevtools 0.21.0 → 0.22.0

package/examples/gg/templates/racing.c

@@ -33,10 +33,13 @@ extern void    gg_sat_upload(void);
 #define VIS_X1         207   /* 48 + 160 - 1 */
 #define VIS_Y1         167   /* 24 + 144 - 1 */
 
-#define LANE_LEFT_X    (VIS_X0 + 28)    /* 76  */
-#define LANE_MID_X     ((VIS_X0 + VIS_X1) / 2 - 4)  /* ~123 */
-#define LANE_RIGHT_X   (VIS_X1 - 36)    /* 171 */
-#define PLAYER_Y       (VIS_Y1 - 16)
+/* Explicit (uint8_t) casts: the computed int expressions all fit in a byte,
+ * but SDCC warns (158) on the implicit int->uint8_t narrowing in the const
+ * initializers below unless the conversion is spelled out. */
+#define LANE_LEFT_X    ((uint8_t)(VIS_X0 + 28))           /* 76  */
+#define LANE_MID_X     ((uint8_t)((VIS_X0 + VIS_X1) / 2 - 4))  /* ~123 */
+#define LANE_RIGHT_X   ((uint8_t)(VIS_X1 - 36))           /* 171 */
+#define PLAYER_Y       ((uint8_t)(VIS_Y1 - 16))
 #define MAX_OBSTACLES   4
 
 /* GG palette = 32 entries × 2 bytes (4-4-4 BGR LE): low=(g<<4)|r, high=b.

package/examples/gg/templates/sports.c

@@ -30,8 +30,11 @@ extern void    gg_sat_upload(void);
 #define COURT_BOT   VIS_Y1
 #define PADDLE_H    24
 #define BALL_SIZE   8
-#define PADDLE_X1   (VIS_X0 + 8)    /* near the visible left edge   */
-#define PADDLE_X2   (VIS_X1 - 16)   /* near the visible right edge  */
+/* Explicit (uint8_t) casts: these fit a byte but SDCC warns (158) on the
+ * implicit int->uint8_t narrowing when the computed macro is passed to the
+ * uint8_t x/y args of gg_sprite_set. */
+#define PADDLE_X1   ((uint8_t)(VIS_X0 + 8))    /* near the visible left edge   */
+#define PADDLE_X2   ((uint8_t)(VIS_X1 - 16))   /* near the visible right edge  */
 
 /* GG palette = 32 entries × 2 bytes (4-4-4 BGR LE): low=(g<<4)|r, high=b.
  * gg_load_palette reads 64 bytes; a 32-byte array leaves the sprite palette
@@ -127,8 +130,9 @@ void main(void) {
   reset_match();
 
   do {
-    uint8_t p1, p2;
+    uint8_t p1;
     uint8_t slot;
+    int16_t target;
     gg_vblank_wait();
     sfx_update();
 
@@ -145,20 +149,14 @@ void main(void) {
     gg_sat_upload();
 
     p1 = gg_joypad_read();
-    p2 = 0;  /* GG has only one controller — always AI for the right paddle */
 
     if ((p1 & JOY_UP)   && p1y > COURT_TOP)            p1y -= 2;
     if ((p1 & JOY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 2;
 
-    /* P2 input if any, otherwise AI. */
-    if (p2 != 0) {
-      if ((p2 & JOY_UP)   && p2y > COURT_TOP)            p2y -= 2;
-      if ((p2 & JOY_DOWN) && p2y < COURT_BOT - PADDLE_H) p2y += 2;
-    } else {
-      int16_t target = by - PADDLE_H / 2;
-      if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
-      else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
-    }
+    /* GG has only one controller — the right paddle is always AI. */
+    target = by - PADDLE_H / 2;
+    if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
+    else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
 
     if (serve_timer > 0) {
       serve_timer--;

package/examples/gg/templates/tile_engine.c

@@ -46,8 +46,9 @@ extern void gg_sat_upload(void);
  * (entries 16-31) reading garbage = invisible sprites. BG colour 1 = entry 1
  * (dark grey wall); sprite colour 1 = entry 17 (white player). */
 static const uint8_t palette[64] = {
-  /* BG 0-15: entry 0 = dark navy backdrop, entry 1 = dark grey wall */
-  0x20,0x02, 0x66,0x06, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* BG 0-15: 0 = dark navy backdrop, 1 = grey wall, 2 = teal floor,
+   * 3 = blue floor (the two floor-dither tones). */
+  0x20,0x02, 0x66,0x06, 0xC8,0x08, 0x80,0x0C, 0,0, 0,0, 0,0, 0,0,
   0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
   /* SPRITE 16-31: 16=transparent, 17=white player */
   0,0, 0xFF,0x0F, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
@@ -55,10 +56,15 @@ static const uint8_t palette[64] = {
 };
 
 static const uint8_t bg_tiles[32 * 2] = {
-  /* T_OPEN — 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,
-  /* T_WALL — bordered block */
+  /* T_OPEN — dithered floor: plane1=0xFF (colour-2 bit always on), plane0
+   * alternates 0xAA/0x55 so pixels flip between colour 2 (teal) and colour 3
+   * (blue). The open floor now fills with TWO tones instead of the backdrop,
+   * so the screen never reads as a single flat colour. */
+  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,
+  /* T_WALL — bordered block (colour 1, grey) */
   0xFF,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
   0x81,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
   0x81,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,

package/examples/lynx/templates/hello_sprite.c

@@ -22,7 +22,21 @@ void main(void) {
   sfx_tone(0, 80, 12);  /* boot chime */
 
   for (;;) {
-    tgi_clear();
+    /* CANONICAL LYNX FRAME LOOP — full redraw every frame:
+     *   1. WAIT for Suzy's blitter to finish the previous frame. Drawing
+     *      while it's mid-flight loses the frame → black screen. This is
+     *      the #1 "Lynx stays blank" trap (tgi_clear alone leaves the back
+     *      page stale on this core, so we clear with a full-screen bar). */
+    while (tgi_busy()) { }
+
+    /* Blue field so the screen is obviously not blank... */
+    tgi_setcolor(COLOR_BLUE);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());
+    /* ...with a green band so no single colour fills the whole screen. */
+    tgi_setcolor(COLOR_GREEN);
+    tgi_bar(0, 60, tgi_getmaxx(), 102);
+
+    /* The joystick-driven player square on top. */
     tgi_setcolor(COLOR_YELLOW);
     tgi_bar(x, y, x + 8, y + 8);
     tgi_setcolor(COLOR_WHITE);

package/examples/lynx/templates/music_demo.c

@@ -26,7 +26,19 @@ void main(void) {
   lynx_snd_play(0, (unsigned char *)demo_music);
 
   for (;;) {
-    tgi_clear();
+    /* CANONICAL LYNX FRAME LOOP — full redraw every frame: WAIT for Suzy's
+     * blitter (drawing mid-flight loses the frame → black), then clear with
+     * a full-screen bar (tgi_clear leaves the back page stale on this core)
+     * before drawing. The #1 "Lynx stays blank" trap. */
+    while (tgi_busy()) { }
+
+    /* Two colour bands so the backdrop is obviously not blank and no single
+     * colour fills the whole screen (a flat fill still reads as "blank"). */
+    tgi_setcolor(COLOR_BLUE);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());
+    tgi_setcolor(COLOR_PURPLE);
+    tgi_bar(0, 56, tgi_getmaxx(), 102);
+
     tgi_setcolor(COLOR_WHITE);
     tgi_outtextxy(20, 20, "LYNX MUSIC DEMO");
     tgi_setcolor(COLOR_YELLOW);

package/examples/nes/templates/hello_sprite.c

@@ -32,6 +32,21 @@ static const uint8_t tile_data[16] = {
   0,    0,    0,    0,    0,    0,    0,    0,
 };
 
+/* 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
+ * Checkerboarded across the nametable below. BG fetches from $1000-$1FFF
+ * under the default PPUCTRL, so these upload to the BG pattern table. */
+static const uint8_t bg_tiles[2 * 16] = {
+  /* tile 1: solid colour 1 */
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  /* tile 2: solid colour 2 */
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+};
+
 /* 32-byte palette: 4 BG palettes + 4 sprite palettes.
  * BG  index 0 ($3F00) is the universal backdrop.
  * SPR index 0 ($3F10) is transparent — always; the value is written
@@ -49,6 +64,21 @@ static const uint8_t palette[32] = {
   0x0F, 0x2A, 0x1A, 0x0A,
 };
 
+/* Fill nametable 0 ($2000) with a checkerboard of BG tiles 1 and 2 so the
+ * screen behind the sprite is visibly NOT blank. Attribute table stays at
+ * palette 0. Caller must have the PPU off. */
+static void fill_bg(void) {
+  uint16_t addr;
+  uint8_t y, x;
+  for (y = 0; y < 30; y++) {
+    addr = (uint16_t)(0x2000 + (uint16_t)y * 32);
+    for (x = 0; x < 32; x++) {
+      vram_unsafe_set(addr, (uint8_t)(((x ^ y) & 1) + 1));
+      ++addr;
+    }
+  }
+}
+
 void main(void) {
   uint8_t px = 124;       /* mid-screen X */
   uint8_t py = 110;       /* mid-screen Y */
@@ -64,6 +94,11 @@ void main(void) {
    * at $0000-$0FFF since the default PPUCTRL has sprite_pattern=0. */
   chr_ram_upload(0x0010, tile_data, 16);
 
+  /* ── 2b. Upload BG tiles to the BG pattern table at $1000 and paint
+   * a checkerboard backdrop so the sprite isn't alone on a blank field. */
+  chr_ram_upload(0x1000, bg_tiles, sizeof(bg_tiles));
+  fill_bg();
+
   /* ── 3. Load palette ─────────────────────────────────────────── */
   palette_load(palette);
 

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/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:");

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/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/shmup_2p.c

@@ -24,6 +24,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);
@@ -40,13 +41,32 @@ extern void    sms_sat_upload(void);
 #define T_ENEMY   3
 
 static const uint8_t palette[32] = {
-  0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  /* BG palette: 0 backdrop space-blue, 1 mid-blue, 2 dark-blue (starfield dither) */
+  0x10, 0x24, 0x14, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   /* Sprite palette: 1 white (P1), 2 yellow (bullet), 3 red (enemy + P2 highlight) */
   0x00, 0x3F, 0x0F, 0x03, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
 };
 
+/* One dithered BG tile (BG bank $0000): plane0=0xAA/0x55, plane1=0x55/0xAA
+ * so pixels alternate colour 1 (mid-blue) and colour 2 (dark-blue) in a fine
+ * checkerboard. Filling the name table with it gives a two-tone "space"
+ * backdrop so the screen never reads as a single flat colour. */
+static const uint8_t bg_tiles[32] = {
+  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,
+};
+
+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);
+}
+
 /* 4 sprite tiles back-to-back: P1 ship (col1), P2 ship (col3), bullet (col2), enemy (col3). */
 static const uint8_t sprite_tiles[32 * 4] = {
   /* P1 ship — diamond, colour 1 (plane 0) */
@@ -112,6 +132,9 @@ void main(void) {
   uint8_t prev1 = 0, prev2 = 0;
   sms_vdp_init();
   sms_load_palette(palette);
+  /* BG dither tile → BG bank $0000, paint the whole name table. */
+  sms_load_tiles(0x0000, bg_tiles, 32);
+  draw_bg();
   sms_load_tiles(0x2000, sprite_tiles, 32 * 4);
 
   p1.x = 80;  p1.y = 160; p1.alive = 1;

package/examples/sms/templates/sports.c

@@ -123,6 +123,7 @@ void main(void) {
   do {
     uint8_t p1, p2;
     uint8_t slot;
+    int16_t target;
     sms_vblank_wait();
     sfx_update();
 
@@ -144,12 +145,13 @@ void main(void) {
     if ((p1 & JOY_UP)   && p1y > COURT_TOP)            p1y -= 2;
     if ((p1 & JOY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 2;
 
-    /* P2 input if any, otherwise AI. */
+    /* P2 input if any, otherwise AI. (`target` is declared at the top of the
+     * loop body — SDCC is C89, declarations must precede statements.) */
     if (p2 != 0) {
       if ((p2 & JOY_UP)   && p2y > COURT_TOP)            p2y -= 2;
       if ((p2 & JOY_DOWN) && p2y < COURT_BOT - PADDLE_H) p2y += 2;
     } else {
-      int16_t target = by - PADDLE_H / 2;
+      target = by - PADDLE_H / 2;
       if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
       else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
     }