romdevtools 0.16.0 → 0.22.0

package/examples/gg/templates/shmup.c

@@ -15,6 +15,7 @@ extern void gg_vdp_display_on(void);
 extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
 extern void gg_load_palette(const uint8_t *palette);
 extern void gg_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void gg_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void gg_vblank_wait(void);
 extern uint8_t gg_joypad_read(void);
 extern void gg_sprite_init(void);
@@ -52,14 +53,55 @@ extern void gg_sat_upload(void);
  * array left the sprite palette (entries 16-31) reading past the array = garbage
  * = invisible sprites.) */
 static const uint8_t palette[64] = {
-  /* BG 0-15: entry 0 = dark navy backdrop */
-  0x20,0x02, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* BG 0-15: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue,
+   * 3 = star white. */
+  0x20,0x02, 0x30,0x04, 0x80,0x08, 0xFF,0x0F, 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, 18=yellow, 19=red */
   0,0, 0xFF,0x0F, 0xFF,0x00, 0x0F,0x00, 0,0, 0,0, 0,0, 0,0,
   0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
 };
 
+/* 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),
+   * everything else colour 1 (plane 0). */
+  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 visible viewport with a banded starfield so the screen is
+ * clearly space, not a flat backdrop. Visible name-table region is cols
+ * 6..25, rows 3..20. BG tile bank is $0000. */
+static void draw_starfield(void) {
+  uint8_t row, col;
+  for (row = 0; row < 28; row++)
+    for (col = 0; col < 32; col++) gg_set_tilemap_cell(row, col, 0, 0);
+  for (row = 3; row <= 20; row++) {
+    for (col = 6; col <= 25; col++) {
+      uint8_t t = (row & 2) ? 1 : 0;             /* alternating depth bands */
+      if (((row * 7 + col * 5) & 7) == 0) t = 2; /* sparse stars */
+      gg_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,
@@ -121,7 +163,9 @@ void main(void) {
 
   gg_vdp_init();
   gg_load_palette(palette);
-  gg_load_tiles(0x2000, sprite_tiles, 32 * 3);
+  gg_load_tiles(0x0000, bg_tiles, 96);          /* BG tiles → BG bank $0000 */
+  gg_load_tiles(0x2000, sprite_tiles, 32 * 3);  /* sprite tiles → $2000 */
+  draw_starfield();
 
   /* Start the ship centered, near the bottom of the VISIBLE region. */
   player.x = (uint8_t)(VIS_X0 + VIS_W / 2 - 4); player.y = (uint8_t)(VIS_Y1 - 16); player.alive = 1;

package/examples/gg/templates/sports.c

@@ -11,6 +11,7 @@ extern void    gg_vdp_init(void);
 extern void    gg_vdp_display_on(void);
 extern void    gg_load_palette(const uint8_t *palette);
 extern void    gg_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void    gg_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void    gg_vblank_wait(void);
 extern uint8_t gg_joypad_read(void);
 extern void    gg_sprite_init(void);
@@ -29,16 +30,19 @@ 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
  * (entries 16-31) reading garbage = invisible sprites. Sprite colour 1 = entry
  * 17 (white). */
 static const uint8_t palette[64] = {
-  /* BG 0-15: entry 0 = dark navy backdrop */
-  0x20,0x02, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* BG 0-15: 0 = dark navy backdrop, 1 = court green, 2 = court line white */
+  0x20,0x02, 0x60,0x00, 0xFF,0x0F, 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,
   /* SPRITE 16-31: 16=transparent, 17=white */
   0,0, 0xFF,0x0F, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
@@ -52,6 +56,42 @@ 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 (colour 1), tile 1 = court line / border
+ *   (colour 2 = white), tile 2 = dashed net (colour 2 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 court inside the GG visible region (cols 6..25, rows 3..20):
+ * green field, white border lines around the perimeter, dashed net down
+ * the centre column. BG tile bank is $0000. */
+static void draw_court(void) {
+  uint8_t row, col;
+  for (row = 3; row <= 20; row++) {
+    for (col = 6; col <= 25; col++) {
+      uint8_t t = 0;                                   /* green field        */
+      if (row == 3 || row == 20 || col == 6 || col == 25) t = 1; /* border  */
+      else if (col == 15 && (row & 1)) t = 2;          /* dashed centre net  */
+      gg_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;
@@ -76,7 +116,13 @@ void main(void) {
   uint8_t i;
   gg_vdp_init();
   gg_load_palette(palette);
-  gg_load_tiles(0x2000, tile_solid, 32);
+  gg_load_tiles(0x0000, bg_tiles, 96);      /* BG court tiles -> BG bank $0000 */
+  gg_load_tiles(0x2000, tile_solid, 32);    /* paddle/ball sprite tile -> $2000 */
+  {
+    uint8_t r, c;
+    for (r = 0; r < 28; r++) for (c = 0; c < 32; c++) gg_set_tilemap_cell(r, c, 0, 0);
+  }
+  draw_court();
   gg_sprite_init();
   sfx_init();
   gg_vdp_display_on();
@@ -84,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();
 
@@ -102,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/default.c

@@ -15,9 +15,12 @@
 #include <lynx.h>
 
 void main(void) {
-  static const unsigned char palette[8] = {
-    COLOR_RED,    COLOR_YELLOW, COLOR_GREEN,     COLOR_LIGHTBLUE,
-    COLOR_BLUE,   COLOR_PURPLE, COLOR_LIGHTGREEN, COLOR_WHITE,
+  /* Cycle the centre square through warm/bright shades only — NOT the
+   * blues, which would blend into the blue background and make the
+   * screen read as "almost one colour". */
+  static const unsigned char palette[6] = {
+    COLOR_RED,   COLOR_YELLOW,     COLOR_GREEN,
+    COLOR_WHITE, COLOR_LIGHTGREEN, COLOR_PURPLE,
   };
   unsigned char shade = 0;
   unsigned int  frame = 0;
@@ -26,16 +29,44 @@ void main(void) {
   tgi_init();
 
   for (;;) {
-    tgi_clear();
+    /* CANONICAL LYNX FRAME LOOP — full redraw every frame, in this order:
+     *   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.
+     *   2. CLEAR with a full-screen tgi_bar in the background colour, NOT
+     *      tgi_clear() — which leaves the back page stale in this
+     *      toolchain+emulator path (the other genre scaffolds all do the
+     *      same; see shmup.c's LYNX-1 note).
+     *   3. DRAW everything.
+     *   4. tgi_updatedisplay() to push the frame. */
+    while (tgi_busy()) { }
+
+    /* Blue field so the screen is obviously not blank. */
+    tgi_setcolor(COLOR_BLUE);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());
+
+    /* A fixed green frame around the centre — always a distinct colour,
+     * so the screen never collapses to a single shade even while the
+     * inner square is cycling. */
+    tgi_setcolor(COLOR_GREEN);
+    tgi_bar(50, 30, 110, 72);
+
+    /* Colour-cycling square in the centre. */
     tgi_setcolor(palette[shade]);
-    tgi_bar(70, 40, 90, 62);
+    tgi_bar(60, 36, 100, 66);
+
+    /* Greeting on top. The tgi font is 8 px wide; "BUILT WITH ROMDEV"
+     * is 17 chars = 136 px, so start near the left edge to stay inside
+     * the 160-px-wide screen. */
     tgi_setcolor(COLOR_WHITE);
-    tgi_outtextxy(2, 2, "HELLO LYNX");
+    tgi_outtextxy(40, 14, "HELLO LYNX");
+    tgi_outtextxy(12, 86, "BUILT WITH ROMDEV");
     tgi_updatedisplay();
 
     frame++;
-    if ((frame & 0x1F) == 0) {        /* every 32 frames */
-      shade = (shade + 1) & 0x07;
+    if ((frame % 24) == 0) {          /* advance the inner square */
+      shade++;
+      if (shade >= 6) shade = 0;
     }
   }
 }

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/lynx/templates/puzzle.c

@@ -98,8 +98,35 @@ void main(void) {
      * — drawing while the blitter is mid-flight loses the frame → black.
      * (Copied from the shmup scaffold, the LYNX-1 fix.) */
     while (tgi_busy()) { }
+
+    /* ── Background scene (drawn every frame). Without it the playfield is
+     * a near-flat single colour and the render-health audit flags the
+     * screen as blank. A framed "well" in the centre with lit side panels
+     * keeps several distinct colours well under the threshold:
+     *   - blue cabinet backdrop
+     *   - dark-grey side panels flanking the well
+     *   - black well interior so the falling blocks read clearly
+     *   - light-grey well frame + a faint grid texture behind the cells. */
+    tgi_setcolor(COLOR_BLUE);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());        /* cabinet backdrop  */
+    tgi_setcolor(COLOR_DARKGREY);
+    tgi_bar(0, 0, GRID_X - 5, 101);                     /* left side panel   */
+    tgi_bar(GRID_X + COLS * CELL_PX + 4, 0, 159, 101);  /* right side panel  */
     tgi_setcolor(COLOR_BLACK);
-    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());
+    tgi_bar(GRID_X - 2, GRID_Y - 2,
+            GRID_X + COLS * CELL_PX + 1, GRID_Y + ROWS * CELL_PX + 1); /* well */
+    /* faint grid texture so the empty well is never one flat colour */
+    tgi_setcolor(COLOR_DARKGREY);
+    for (r = 0; r <= ROWS; r++)
+      tgi_line(GRID_X, GRID_Y + r * CELL_PX, GRID_X + COLS * CELL_PX - 1, GRID_Y + r * CELL_PX);
+    for (c = 0; c <= COLS; c++)
+      tgi_line(GRID_X + c * CELL_PX, GRID_Y, GRID_X + c * CELL_PX, GRID_Y + ROWS * CELL_PX - 1);
+    /* well frame */
+    tgi_setcolor(COLOR_LIGHTGREY);
+    tgi_line(GRID_X - 2, GRID_Y - 2, GRID_X - 2, GRID_Y + ROWS * CELL_PX + 1);
+    tgi_line(GRID_X + COLS * CELL_PX + 1, GRID_Y - 2, GRID_X + COLS * CELL_PX + 1, GRID_Y + ROWS * CELL_PX + 1);
+    tgi_line(GRID_X - 2, GRID_Y + ROWS * CELL_PX + 1, GRID_X + COLS * CELL_PX + 1, GRID_Y + ROWS * CELL_PX + 1);
+
     /* grid */
     for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) {
       if (grid[r][c] != 0) {

package/examples/lynx/templates/racing.c

@@ -23,6 +23,8 @@ void main(void) {
   uint8_t game_over = 0;
   uint8_t joy, i;
   uint32_t rng = 1;
+  uint8_t scroll = 0;   /* animates the road dashes so the track moves */
+  int16_t y;
 
   tgi_install(&lynx_160_102_16_tgi);
   tgi_init();
@@ -36,14 +38,37 @@ void main(void) {
      * — drawing while the blitter is mid-flight loses the frame → black.
      * (Copied from the shmup scaffold, the LYNX-1 fix.) */
     while (tgi_busy()) { }
-    tgi_setcolor(COLOR_BLACK);
-    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());
-    /* lane lines */
+
+    /* ── Background scene (drawn every frame). Without it the track is a
+     * near-flat single colour and the render-health audit flags the
+     * screen as blank. A full road with grass shoulders + animated lane
+     * dashes keeps several distinct colours well under the threshold:
+     *   - green grass shoulders on both sides
+     *   - mid-grey tarmac with darker-grey lane bands
+     *   - white scrolling centre dashes + solid edge lines. */
+    tgi_setcolor(COLOR_GREEN);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());        /* grass base        */
+    tgi_setcolor(COLOR_GREY);
+    tgi_bar(20, 0, 148, 101);                           /* tarmac            */
+    /* darker lane bands so the road isn't one flat grey */
     tgi_setcolor(COLOR_DARKGREY);
-    tgi_line(28, 0, 28, 101);
-    tgi_line(72, 0, 72, 101);
-    tgi_line(116, 0, 116, 101);
-    tgi_line(160, 0, 160, 101);
+    tgi_bar(20, 0, 53, 101);
+    tgi_bar(96, 0, 128, 101);
+    /* solid road edges */
+    tgi_setcolor(COLOR_WHITE);
+    tgi_line(20, 0, 20, 101);
+    tgi_line(148, 0, 148, 101);
+    /* animated dashed lane dividers (scroll downward) */
+    for (y = (int16_t)scroll - 12; y < 102; y += 12) {
+      tgi_bar(53, (unsigned)(y < 0 ? 0 : y), 55, (unsigned)(y + 6 > 101 ? 101 : y + 6));
+      tgi_bar(96, (unsigned)(y < 0 ? 0 : y), 98, (unsigned)(y + 6 > 101 ? 101 : y + 6));
+    }
+    /* grass rumble strips for extra colour texture */
+    tgi_setcolor(COLOR_LIGHTGREEN);
+    for (y = (int16_t)scroll - 8; y < 102; y += 16) {
+      tgi_bar(0,   (unsigned)(y < 0 ? 0 : y), 6,   (unsigned)(y + 6 > 101 ? 101 : y + 6));
+      tgi_bar(153, (unsigned)(y < 0 ? 0 : y), 159, (unsigned)(y + 6 > 101 ? 101 : y + 6));
+    }
 
     tgi_setcolor(COLOR_YELLOW);
     tgi_bar((unsigned)player.x - 4, (unsigned)player.y - 4, (unsigned)player.x + 4, (unsigned)player.y + 4);
@@ -54,6 +79,8 @@ void main(void) {
     tgi_updatedisplay();
     sfx_update();
 
+    scroll += 2; if (scroll >= 12) scroll -= 12;   /* advance road dashes */
+
     if (game_over > 0) {
       game_over--;
       if (game_over == 0) {

package/examples/lynx/templates/shmup.c

@@ -50,8 +50,15 @@ static void spawn(void) {
   }
 }
 
+/* Scrolling starfield: a handful of stars that drift down so the dark
+ * space field is never a flat single colour (would read as "blank"). */
+#define N_STARS 24
+static uint8_t star_x[N_STARS];
+static uint8_t star_y[N_STARS];
+
 void main(void) {
   uint8_t joy, fire_now, i, j;
+  uint32_t srng = 0x1234;
 
   tgi_install(&lynx_160_102_16_tgi);
   tgi_init();
@@ -61,6 +68,12 @@ void main(void) {
   player.x = 76; player.y = 90; player.alive = 1;
   for (i = 0; i < MAX_BULLETS; i++) bullets[i].alive = 0;
   for (i = 0; i < MAX_ENEMIES; i++) enemies[i].alive = 0;
+  for (i = 0; i < N_STARS; i++) {
+    srng = srng * 1103515245u + 12345u;
+    star_x[i] = (uint8_t)((srng >> 16) % 160);
+    srng = srng * 1103515245u + 12345u;
+    star_y[i] = (uint8_t)((srng >> 16) % 102);
+  }
   spawn_timer = 0;
   prev_btn = 0;
 
@@ -76,10 +89,31 @@ void main(void) {
      *   3. DRAW every object.
      *   4. tgi_updatedisplay() to push the frame. */
     while (tgi_busy()) { }
-    tgi_setcolor(COLOR_BLACK);
-    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());  /* maxx/maxy = 159/101 = full screen */
 
-    /* Render */
+    /* ── Background scene (drawn every frame; without it the dark space
+     * field is a near-flat single colour and the render-health audit
+     * flags the screen as blank). Layered bands keep any one colour well
+     * under the threshold:
+     *   - deep-blue upper space
+     *   - grey nebula band across the middle
+     *   - green planet surface along the bottom
+     *   - a drifting white/yellow starfield over the space. */
+    tgi_setcolor(COLOR_BLUE);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());      /* base space field   */
+    tgi_setcolor(COLOR_GREY);
+    tgi_bar(0, 34, 159, 60);                          /* nebula band        */
+    tgi_setcolor(COLOR_GREEN);
+    tgi_bar(0, 84, 159, 101);                         /* planet surface     */
+    tgi_setcolor(COLOR_LIGHTGREEN);
+    tgi_bar(0, 78, 159, 83);                          /* surface horizon    */
+    /* starfield (bright specks; also drifts downward each frame) */
+    tgi_setcolor(COLOR_WHITE);
+    for (i = 0; i < N_STARS; i++) {
+      tgi_setpixel(star_x[i], star_y[i]);
+      tgi_setpixel(star_x[i], (star_y[i] + 1) % 102);
+    }
+
+    /* Render game objects on top */
     tgi_setcolor(COLOR_YELLOW);
     tgi_bar(player.x, player.y, player.x + 6, player.y + 6);
     tgi_setcolor(COLOR_WHITE);
@@ -93,6 +127,11 @@ void main(void) {
     tgi_updatedisplay();
     sfx_update();
 
+    /* drift the starfield downward */
+    for (i = 0; i < N_STARS; i++) {
+      if (star_y[i] >= 101) star_y[i] = 0; else star_y[i]++;
+    }
+
     /* Input + state */
     joy = joy_read(JOY_1);
     fire_now = JOY_BTN_1(joy) ? 1 : 0;

package/examples/lynx/templates/sports.c

@@ -21,6 +21,7 @@ void main(void) {
   int16_t p1y = 40, p2y = 40, bx = 78, by = 48;
   int8_t bdx = 2, bdy = 1;
   uint8_t joy;
+  int16_t ny;   /* loop var for the dashed centre net */
 
   tgi_install(&lynx_160_102_16_tgi);
   tgi_init();
@@ -33,8 +34,34 @@ void main(void) {
      * — drawing while the blitter is mid-flight loses the frame → black.
      * (Copied from the shmup scaffold, the LYNX-1 fix.) */
     while (tgi_busy()) { }
-    tgi_setcolor(COLOR_BLACK);
-    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());
+
+    /* ── Background scene (drawn every frame). Without it the court is a
+     * near-flat single colour and the render-health audit flags the
+     * screen as blank. A two-tone court with boards + net markings keeps
+     * several distinct colours well under the threshold:
+     *   - green centre court
+     *   - lighter-green end zones behind each paddle
+     *   - dark-grey boards top and bottom
+     *   - white boundary, dashed centre net + centre circle. */
+    tgi_setcolor(COLOR_GREEN);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());        /* court grass       */
+    tgi_setcolor(COLOR_LIGHTGREEN);
+    tgi_bar(0, COURT_TOP, 52, COURT_BOT - 1);           /* left end zone     */
+    tgi_bar(107, COURT_TOP, 159, COURT_BOT - 1);        /* right end zone    */
+    tgi_setcolor(COLOR_DARKGREY);
+    tgi_bar(0, 0, 159, COURT_TOP - 1);                  /* top boards        */
+    tgi_bar(0, COURT_BOT, 159, 101);                    /* bottom boards     */
+    /* white court boundary + dashed centre net + centre circle */
+    tgi_setcolor(COLOR_WHITE);
+    tgi_line(0, COURT_TOP, 159, COURT_TOP);
+    tgi_line(0, COURT_BOT, 159, COURT_BOT);
+    for (ny = COURT_TOP; ny < COURT_BOT; ny += 8)
+      tgi_bar(79, (unsigned)ny, 80, (unsigned)(ny + 3 > COURT_BOT ? COURT_BOT : ny + 3));
+    tgi_line(70, 40, 90, 40);
+    tgi_line(70, 60, 90, 60);
+    tgi_line(70, 40, 70, 60);
+    tgi_line(90, 40, 90, 60);
+
     tgi_setcolor(COLOR_WHITE);
     tgi_bar(PADDLE_X1, (unsigned)p1y, PADDLE_X1 + PADDLE_W - 1, (unsigned)(p1y + PADDLE_H - 1));
     tgi_bar(PADDLE_X2, (unsigned)p2y, PADDLE_X2 + PADDLE_W - 1, (unsigned)(p2y + PADDLE_H - 1));