romdevtools 0.16.0 → 0.22.0

package/examples/genesis/templates/shmup.c

@@ -30,8 +30,22 @@
 #define T_SHIP   (TILE_USER_INDEX + 1)
 #define T_BULLET (TILE_USER_INDEX + 2)
 #define T_ENEMY  (TILE_USER_INDEX + 3)
+#define T_SPACE  (TILE_USER_INDEX + 4)   /* nebula backdrop A (BG_B) */
+#define T_STARS  (TILE_USER_INDEX + 5)   /* nebula backdrop B (BG_B) */
 
 static const u32 tile_blank[8]  = { 0,0,0,0,0,0,0,0 };
+/* Deep-space backdrop tiled across BG_B so the playfield isn't a flat
+ * black void. Two distinct nebula blocks are checkerboarded so no single
+ * colour dominates the screen: T_SPACE is colour-4 nebula with colour-5
+ * star dots; T_STARS swaps the roles (colour-5 field, colour-4 dots). */
+static const u32 tile_space[8]  = {
+    0x44444444, 0x44455444, 0x44444444, 0x54444445,
+    0x44444444, 0x44455444, 0x44444444, 0x54444445,
+};
+static const u32 tile_stars[8]  = {
+    0x55555555, 0x55544555, 0x55555555, 0x45555554,
+    0x55555555, 0x55544555, 0x55555555, 0x45555554,
+};
 static const u32 tile_ship[8]   = {
     0x00011000, 0x00011000, 0x00111100, 0x00111100,
     0x01111110, 0x01111110, 0x11111111, 0x11000011,
@@ -102,8 +116,10 @@ int main(bool hard) {
 
     /* PAL0 — used by player + font */
     PAL_setColor(0 + 1, 0x0EEE); /* ship white */
-    /* PAL1 — bullet */
+    /* PAL1 — bullet + space backdrop */
     PAL_setColor(16 + 2, 0x00EE); /* bullet yellow */
+    PAL_setColor(16 + 4, 0x0600); /* nebula deep blue  */
+    PAL_setColor(16 + 5, 0x0402); /* nebula violet     */
     /* PAL2 — enemy */
     PAL_setColor(32 + 3, 0x000E); /* enemy red */
 
@@ -113,6 +129,20 @@ int main(bool hard) {
     VDP_loadTileData(tile_ship,   T_SHIP,   1, DMA);
     VDP_loadTileData(tile_bullet, T_BULLET, 1, DMA);
     VDP_loadTileData(tile_enemy,  T_ENEMY,  1, DMA);
+    VDP_loadTileData(tile_space,  T_SPACE,  1, DMA);
+    VDP_loadTileData(tile_stars,  T_STARS,  1, DMA);
+
+    /* Fill the far plane (BG_B) with the space backdrop so the screen
+     * isn't an empty black void; sprinkle denser star clusters for
+     * variety. Sprites (ship/bullets/enemies) always draw above the
+     * planes, so the gameplay reads on top of this with no priority
+     * juggling. */
+    for (u16 cy = 0; cy < 28; cy++)
+        for (u16 cx = 0; cx < 40; cx++)
+            VDP_setTileMapXY(BG_B,
+                TILE_ATTR_FULL(PAL1, 0, 0, 0,
+                    ((cx ^ cy) & 1) ? T_STARS : T_SPACE),
+                cx, cy);
 
     player.x = 152; player.y = 180; player.alive = TRUE;
     for (u16 i = 0; i < MAX_BULLETS; i++) bullets[i].alive = FALSE;

package/examples/genesis/templates/shmup_2p.c

@@ -30,8 +30,22 @@
 #define T_SHIP_P2 (TILE_USER_INDEX + 2)
 #define T_BULLET  (TILE_USER_INDEX + 3)
 #define T_ENEMY   (TILE_USER_INDEX + 4)
+#define T_SPACE   (TILE_USER_INDEX + 5)   /* nebula backdrop A (BG_B) */
+#define T_STARS   (TILE_USER_INDEX + 6)   /* nebula backdrop B (BG_B) */
 
 static const u32 tile_blank[8]   = { 0,0,0,0,0,0,0,0 };
+/* Deep-space backdrop tiled across BG_B so the shared playfield isn't a
+ * flat black void. Two distinct nebula blocks are checkerboarded so no
+ * single colour dominates: T_SPACE is colour-5 nebula with colour-6 star
+ * dots; T_STARS swaps the roles. Palette 1, colours set in main(). */
+static const u32 tile_space[8]   = {
+    0x55555555, 0x55566555, 0x55555555, 0x65555556,
+    0x55555555, 0x55566555, 0x55555555, 0x65555556,
+};
+static const u32 tile_stars[8]   = {
+    0x66666666, 0x66655666, 0x66666666, 0x56666665,
+    0x66666666, 0x66655666, 0x66666666, 0x56666665,
+};
 /* P1 ship — palette 0 colour 1 (white). */
 static const u32 tile_ship_p1[8] = {
     0x00011000, 0x00011000, 0x00111100, 0x00111100,
@@ -116,6 +130,10 @@ int main(bool hard) {
     PAL_setColor(0 + 1, 0x0EEE);
     PAL_setColor(0 + 2, 0x00EE);
     PAL_setColor(0 + 4, 0x000E);
+    /* Palette 1 = space backdrop (colours 5/6, kept clear of the PAL0
+     * sprite colours so the shared planes never clash). */
+    PAL_setColor(16 + 5, 0x0600); /* nebula deep blue */
+    PAL_setColor(16 + 6, 0x0402); /* nebula violet    */
     /* Palette 2 = enemy red */
     PAL_setColor(32 + 3, 0x00EE);
 
@@ -126,6 +144,19 @@ int main(bool hard) {
     VDP_loadTileData(tile_ship_p2, T_SHIP_P2, 1, DMA);
     VDP_loadTileData(tile_bullet,  T_BULLET,  1, DMA);
     VDP_loadTileData(tile_enemy,   T_ENEMY,   1, DMA);
+    VDP_loadTileData(tile_space,   T_SPACE,   1, DMA);
+    VDP_loadTileData(tile_stars,   T_STARS,   1, DMA);
+
+    /* Fill the far plane (BG_B) with the space backdrop so the shared
+     * playfield isn't an empty black void; sprites always draw above the
+     * planes, so both ships + bullets + enemies read on top with no
+     * priority juggling. */
+    for (u16 cy = 0; cy < 28; cy++)
+        for (u16 cx = 0; cx < 40; cx++)
+            VDP_setTileMapXY(BG_B,
+                TILE_ATTR_FULL(PAL1, 0, 0, 0,
+                    ((cx ^ cy) & 1) ? T_STARS : T_SPACE),
+                cx, cy);
 
     p1.x = 100; p1.y = 180; p1.alive = TRUE;
     p2.x = 220; p2.y = 180; p2.alive = TRUE;

package/examples/genesis/templates/xgm2_demo.c

@@ -25,9 +25,29 @@
  * (the byte layout produced by `xgm2tool input.vgm output.xgc`). */
 extern const u8 music_xgm[];
 
+/* A backdrop block tiled across plane B so the title screen isn't a flat
+ * black void (text alone on black reads as "blank" to a human). Colour
+ * index 4 field with a colour-5 frame — both set below. */
+static const u32 tile_bg[8] = {
+    0x44444444, 0x45555554, 0x45000054, 0x45000054,
+    0x45000054, 0x45000054, 0x45555554, 0x44444444,
+};
+
+#define T_BG (TILE_USER_INDEX + 0)
+
 int main(bool hard) {
     (void)hard;
 
+    /* Plane-B backdrop colours (palette 1) + a tiled backdrop so the
+     * music-demo title screen has a visible background behind the text.
+     * Plane A (the font) draws above plane B, so the text reads on top. */
+    PAL_setColor(16 + 4, 0x0840); /* dark green field */
+    PAL_setColor(16 + 5, 0x0C60); /* lighter frame    */
+    VDP_loadTileData(tile_bg, T_BG, 1, DMA);
+    for (u16 cy = 0; cy < 28; cy++)
+        for (u16 cx = 0; cx < 40; cx++)
+            VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_BG), cx, cy);
+
     /* Title screen text — drawn into VDP plane A's default font region. */
     VDP_drawText("XGM2 MUSIC DEMO",        12, 10);
     VDP_drawText("ROM-DEV-MCP / SGDK",     10, 12);

package/examples/gg/templates/default.c

@@ -1,17 +1,17 @@
-/* Game Gear hello-world. Writes a yellow 'H' tile to VRAM, places it in
- * the center of the 160×144 visible viewport, enables display. Pressing
- * P1-B1 scrolls the BG by one pixel per frame.
+/* Game Gear hello-world. Paints the whole 160×144 visible viewport with
+ * a blue BG panel, drops a yellow 'H' tile in its centre, enables
+ * display. Pressing P1-B1 scrolls the BG by one pixel per frame.
  *
- * Self-contained — inlines the VDP helpers so this single file + the
+ * Self-contained — inlines the VDP helpers so this single file plus the
  * bundled gg_crt0.s are all you need to compile and run. For a more
- * modular multi-file project that pulls in src/platforms/gg/lib/c/*,
+ * modular multi-file project that pulls in the bundled GG runtime,
  * see `hello_sprite` and `tile_engine`.
  *
  * GG specifics this file demonstrates (read MENTAL_MODEL.md for details):
  *   - Visible viewport is 160×144 centered in the 256×192 framebuffer.
  *     OAM/name-table coords are in 256×192 space; the visible region
- *     starts at hw coord (48, 24). The 'H' goes at name-table row 12
- *     col 16 = visible center.
+ *     starts at hw coord (48, 24). The 'H' goes at name-table row 11
+ *     col 15 = visible center.
  *   - CRAM entries are 12-bit BGR (2 bytes each, little-endian), 16 BG
  *     colors at $0000-$1F and 16 sprite colors at $0020-$3F.
  *   - VDP R6 default is 0xFB → sprite tiles read from $0000 (NOT $2000
@@ -86,13 +86,17 @@ static void vdp_init(void) {
 static const uint8_t palette[32] = {
   0x00, 0x00,   /* 0  backdrop (black) */
   0xFF, 0x00,   /* 1  yellow */
-  0x00, 0x00,   0x00, 0x00,   0x00, 0x00,   0x00, 0x00,
+  0x00, 0x0F,   /* 2  blue (panel fill A) */
+  0x0F, 0x00,   /* 3  red  (panel fill B) */
+  0x00, 0x00,   0x00, 0x00,
   0x00, 0x00,   0x00, 0x00,   0x00, 0x00,   0x00, 0x00,
   0x00, 0x00,   0x00, 0x00,   0x00, 0x00,   0x00, 0x00,
 };
 
-/* 8×8 4bpp tile of an 'H'. Mode 4 stores 4 bytes per scanline (one per
- * bitplane). Setting plane 0 only → color index 1 = yellow. */
+/* Tile 1 = an 'H' glyph. Tile 2 = a solid colour-2 fill used to paint
+ * the whole visible viewport so the screen is obviously not blank.
+ * Mode 4 stores 4 bytes per scanline (one per bitplane). Plane 0 set →
+ * colour index 1; plane 1 set → colour index 2. */
 static const uint8_t tile_h[32] = {
   0x66, 0x00, 0x00, 0x00,
   0x66, 0x00, 0x00, 0x00,
@@ -103,6 +107,21 @@ static const uint8_t tile_h[32] = {
   0x66, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00,
 };
+/* Tile 2 = solid colour 2 (blue). Tile 3 = solid colour 3 (red). The
+ * viewport is painted as a blue/red checkerboard so no single colour
+ * dominates the screen — a clear "it works" panel, not a flat fill. */
+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,
+};
 
 static void load_palette(void) {
   uint8_t i;
@@ -110,23 +129,42 @@ static void load_palette(void) {
   for (i = 0; i < 32; i++) PORT_VDP_DATA = palette[i];
 }
 
-static void load_tile(void) {
+static void load_tiles(void) {
   uint8_t i;
   vdp_set_addr(32, VDP_VRAM_WRITE);    /* tile slot 1 = VRAM offset 32 */
   for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_h[i];
+  vdp_set_addr(64, VDP_VRAM_WRITE);    /* tile slot 2 = VRAM offset 64 */
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_fill2[i];
+  vdp_set_addr(96, VDP_VRAM_WRITE);    /* tile slot 3 = VRAM offset 96 */
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_fill3[i];
 }
 
-static void clear_name_table(void) {
+/* Clear the whole 32×28 name table, then paint the visible 160×144
+ * viewport (cols 6..25, rows 3..20) as a solid blue panel inside a red
+ * border frame — a clean "it works" screen that is obviously neither
+ * blank nor a single flat colour. */
+static void draw_background(void) {
+  uint8_t row, col, fill;
   uint16_t i;
   vdp_set_addr(0x3800, VDP_VRAM_WRITE);
   for (i = 0; i < 1792; i++) PORT_VDP_DATA = 0;
+  for (row = GG_VIS_ROW_MIN; row <= GG_VIS_ROW_MAX; row++) {
+    vdp_set_addr(0x3800 + (row * 32 + GG_VIS_COL_MIN) * 2, VDP_VRAM_WRITE);
+    for (col = GG_VIS_COL_MIN; col <= GG_VIS_COL_MAX; col++) {
+      if (row == GG_VIS_ROW_MIN || row == GG_VIS_ROW_MAX ||
+          col == GG_VIS_COL_MIN || col == GG_VIS_COL_MAX)
+        fill = 3;   /* red border */
+      else
+        fill = 2;   /* blue interior */
+      PORT_VDP_DATA = fill;
+      PORT_VDP_DATA = 0;
+    }
+  }
 }
 
-/* Drop the 'H' at name-table (row 12, col 16). Visible GG viewport
- * sits at name-table cols 6..25 / rows 3..20 — so (12,16) is roughly
- * the visible center. */
+/* Drop the 'H' at name-table (row 11, col 15) — the visible centre. */
 static void place_h(void) {
-  vdp_set_addr(0x3800 + (12 * 32 + 16) * 2, VDP_VRAM_WRITE);
+  vdp_set_addr(0x3800 + (11 * 32 + 15) * 2, VDP_VRAM_WRITE);
   PORT_VDP_DATA = 1;
   PORT_VDP_DATA = 0;
 }
@@ -140,8 +178,8 @@ void main(void) {
 
   vdp_init();
   load_palette();
-  load_tile();
-  clear_name_table();
+  load_tiles();
+  draw_background();
   place_h();
 
   vdp_write_reg(1, 0xE0);   /* display ON, vblank IRQ on, 192-line */

package/examples/gg/templates/hello_sprite.c

@@ -29,6 +29,7 @@ extern void gg_vdp_write_reg(uint8_t reg, uint8_t value);
 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);
@@ -41,14 +42,33 @@ extern void gg_sat_upload(void);
  * array = garbage = INVISIBLE sprites. Sprite colour index N uses entry 16+N,
  * so sprite colour 1 = entry 17 (white here). */
 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 = teal, 2 = blue (dither tones) */
+  0x20,0x02, 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, 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,
   0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
 };
 
+/* One dithered BG tile (BG bank $0000): plane0/plane1 alternate so pixels
+ * flip between colour 1 (teal) and colour 2 (blue). Filling the name table
+ * with it gives a two-tone backdrop so the frame is never a flat colour —
+ * a uniform fill still reads as a blank screen. The dither fills the whole
+ * 256x192 frame, so it shows in the GG's centered 160x144 window too. */
+static const uint8_t bg_tile[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++)
+      gg_set_tilemap_cell(row, col, 0, 0);
+}
+
 /* ── Game Gear visible viewport ──────────────────────────────────────
  * Sprite OAM uses SMS HARDWARE coordinates (256x192 space), but the GG
  * LCD only shows the CENTER 160x144. Keep the sprite inside this box or
@@ -73,6 +93,9 @@ void main(void) {
 
   gg_vdp_init();
   gg_load_palette(palette);
+  /* BG dither tile → BG bank $0000, paint the whole name table. */
+  gg_load_tiles(0x0000, bg_tile, 32);
+  draw_bg();
   /* Upload one sprite tile to VRAM $2000 (sprite tile area). */
   gg_load_tiles(0x2000, sprite_tile, 32);
 

package/examples/gg/templates/music_demo.c

@@ -30,6 +30,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);
@@ -41,14 +42,32 @@ extern void gg_sat_upload(void);
  * (entries 16-31) reading garbage = invisible sprites. Sprite palette:
  *   16 = transparent, 17 = white, 18 = green, 19 = red. */
 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 = teal, 2 = blue (dither tones) */
+  0x20,0x02, 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, 0,0,
   /* SPRITE 16-31: 16=transparent, 17=white, 18=green, 19=red */
   0,0, 0xFF,0x0F, 0xF0,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,
 };
 
+/* One dithered BG tile (BG bank $0000): plane0/plane1 alternate so pixels
+ * flip between colour 1 (teal) and colour 2 (blue). Filling the name table
+ * with it gives a two-tone backdrop behind the song indicators so the frame
+ * never reads as a single flat colour. */
+static const uint8_t bg_tile[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++)
+      gg_set_tilemap_cell(row, col, 0, 0);
+}
+
 /* Three 8×8 sprite tiles, 4bpp interleaved (4 planes × 8 rows):
  *   tile 0: solid color 1 (white)
  *   tile 1: solid color 2 (green)
@@ -99,6 +118,9 @@ void main(void) {
 
   gg_vdp_init();
   gg_load_palette(palette);
+  /* BG dither tile → BG bank $0000, paint the whole name table. */
+  gg_load_tiles(0x0000, bg_tile, 32);
+  draw_bg();
   gg_load_tiles(0x2000, sprite_tiles, sizeof(sprite_tiles));
   gg_sprite_init();
 

package/examples/gg/templates/platformer.c

@@ -52,11 +52,12 @@ extern void gg_sat_upload(void);
 
 /* 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. BG colour 1 = entry 1
- * (mid-grey wall); sprite colour 1 = entry 17 (white player). */
+ * (entries 16-31) reading garbage = invisible sprites. BG colour 1 = light
+ * sky blue, 2 = darker sky blue (the sky dither), 3 = mid-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 = mid-grey wall */
-  0x20,0x02, 0xAA,0x0A, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* BG 0-15: 0 = dark navy backdrop, 1 = light sky, 2 = dark sky, 3 = wall grey */
+  0x20,0x02, 0xFB,0x0F, 0xC8,0x0C, 0x88,0x08, 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,
@@ -64,14 +65,19 @@ 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 — solid block in colour 1 */
-  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,
+  /* T_OPEN — dithered sky: pixels alternate colour 1 (light) / colour 2
+   * (dark) so the sky fills the screen but no single colour dominates.
+   * plane0 = 0xAA (cols 0,2,4,6 -> colour 1), plane1 = 0x55 (cols 1,3,5,7
+   * -> colour 2). */
+  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,
+  /* T_WALL — solid block in colour 3 (planes 0+1 set) */
+  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,
 };
 
 static const uint8_t player_tile[32] = {

package/examples/gg/templates/puzzle.c

@@ -25,16 +25,19 @@ extern uint8_t gg_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,13 +89,30 @@ 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 */
 }
 
+/* GG shows only the centered cols 6..25 / rows 3..20. Place the 6×12 grid
+ * at tilemap cols 7..12, rows 4..15 so the whole well sits inside that
+ * visible band. */
 static void draw_cell(int8_t col, int8_t row, uint8_t cell) {
   if (row < 0 || row >= ROWS) return;
-  /* Centre the 6-col grid; +7 columns left margin, +1 row top margin. */
-  gg_set_tilemap_cell((uint8_t)(row + 1), (uint8_t)(col + 7), tile_for(cell), 0);
+  gg_set_tilemap_cell((uint8_t)(row + 4), (uint8_t)(col + 7), tile_for(cell), 0);
+}
+
+/* Draw the well: a grey border frame around the 6×12 play field with a dim
+ * field interior, so the playfield is clearly visible even when empty. The
+ * grid maps cell (col,row) -> tilemap (row+4, col+7) = rows 4..15 cols 7..12.
+ * Frame the perimeter at rows 3..16, cols 6..13 — inside the GG viewport. */
+static void draw_well(void) {
+  uint8_t r, c;
+  for (r = 3; r <= 16; r++) {
+    for (c = 6; c <= 13; c++) {
+      uint8_t t = T_FIELD;
+      if (r == 3 || r == 16 || c == 6 || c == 13) t = T_WALL;
+      gg_set_tilemap_cell(r, c, t, 0);
+    }
+  }
 }
 
 static void draw_grid(void) {
@@ -151,7 +181,7 @@ void main(void) {
 
   gg_vdp_init();
   gg_load_palette(palette);
-  gg_load_tiles(0x0000, bg_tiles, 32 * 4);
+  gg_load_tiles(0x0000, bg_tiles, 32 * 6);
 
   for (r = 0; r < 24; r++) for (c = 0; c < 32; c++) gg_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 +189,7 @@ void main(void) {
   score = 0;
   fall_timer = 0;
   new_piece();
+  draw_well();
   draw_grid();
 
   sfx_init();

package/examples/gg/templates/racing.c

@@ -18,6 +18,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);
@@ -32,25 +33,49 @@ 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.
  * 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), colour 2 = entry 18 (red). */
+ * (entries 16-31) reading garbage = invisible sprites. BG colour 1 = grass
+ * green, BG colour 2 = road grey. Sprite colour 1 = entry 17 (white),
+ * colour 2 = entry 18 (red). */
 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 = grass green, 2 = road grey */
+  0x20,0x02, 0x60,0x00, 0x66,0x06, 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, 18=red */
   0,0, 0xFF,0x0F, 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, 0,0,
 };
 
+/* Three BG tiles for the track, loaded into the BG tile bank at $0000:
+ *   tile 0 = blank (all zeros → shows the backdrop colour)
+ *   tile 1 = solid grass (colour 1)
+ *   tile 2 = solid road  (colour 2) */
+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,
+};
+
 /* Two sprite tiles — player (colour 1) + enemy (colour 2). */
 static const uint8_t tiles[64] = {
   /* Tile 0 = player car (colour 1 → plane 0 set) */
@@ -65,6 +90,28 @@ static const uint8_t tiles[64] = {
   0x00,0x7E,0x00,0x00, 0x00,0x66,0x00,0x00,
 };
 
+/* Paint the visible viewport: grey road down the centre lanes, green
+ * grass on the shoulders. Visible name-table region is cols 6..25,
+ * rows 3..20 (the centered 160×144). BG tile bank is $0000. */
+#define VIS_COL_MIN  6
+#define VIS_COL_MAX 25
+#define VIS_ROW_MIN  3
+#define VIS_ROW_MAX 20
+static void draw_track(void) {
+  uint8_t row, col;
+  /* Blank the whole 32×28 name table to backdrop (tile 0). */
+  for (row = 0; row < 28; row++)
+    for (col = 0; col < 32; col++) gg_set_tilemap_cell(row, col, 0, 0);
+  /* Paint the visible viewport: road (tile 2) down the central lanes,
+   * grass (tile 1) on the shoulders. */
+  for (row = VIS_ROW_MIN; row <= VIS_ROW_MAX; row++) {
+    for (col = VIS_COL_MIN; col <= VIS_COL_MAX; col++) {
+      uint8_t road = (col >= VIS_COL_MIN + 4 && col <= VIS_COL_MAX - 4);
+      gg_set_tilemap_cell(row, col, road ? 2 : 1, 0);
+    }
+  }
+}
+
 typedef struct { uint8_t x, y, alive; } Car;
 
 static Car player;
@@ -110,7 +157,9 @@ void main(void) {
   uint8_t i;
   gg_vdp_init();
   gg_load_palette(palette);
-  gg_load_tiles(0x2000, tiles, 64);
+  gg_load_tiles(0x0000, bg_tiles, 96);   /* BG tiles → BG bank $0000 */
+  gg_load_tiles(0x2000, tiles, 64);      /* sprite tiles → sprite bank $2000 */
+  draw_track();
   gg_sprite_init();
   sfx_init();
   gg_vdp_display_on();