romdevtools 0.15.0 → 0.21.0

package/examples/genesis/templates/racing.c

@@ -29,6 +29,8 @@
 #define T_CAR_EN   (TILE_USER_INDEX + 1)
 #define T_LANE     (TILE_USER_INDEX + 2)   /* dashed lane divider (BG_B) */
 #define T_EDGE     (TILE_USER_INDEX + 3)   /* solid road edge      (BG_B) */
+#define T_GRASS    (TILE_USER_INDEX + 4)   /* roadside backdrop    (BG_A) */
+#define T_ASPHALT  (TILE_USER_INDEX + 5)   /* road surface backdrop(BG_A) */
 
 static const u32 tile_car_p1[8] = {
     0x01111110, 0x11111111, 0x12222221, 0x11111111,
@@ -51,6 +53,18 @@ static const u32 tile_edge[8] = {
     0x00000022, 0x00000022, 0x00000022, 0x00000022,
     0x00000022, 0x00000022, 0x00000022, 0x00000022,
 };
+/* Roadside grass (colour 5) with a couple of darker tufts (colour 6) so
+ * it isn't a flat fill — tiled down both shoulders on BG_A. */
+static const u32 tile_grass[8] = {
+    0x55555555, 0x55556555, 0x55555555, 0x65555555,
+    0x55555555, 0x55555565, 0x55555555, 0x55655555,
+};
+/* Road asphalt (colour 6) with faint speckle (colour 5) — tiled across
+ * the driving surface on BG_A, behind the BG_B lane markings + cars. */
+static const u32 tile_asphalt[8] = {
+    0x66666666, 0x66666566, 0x66666666, 0x56666666,
+    0x66666666, 0x66666656, 0x66666666, 0x66566666,
+};
 
 /* The road lives on BG_B (8×8 cells). Two dashed dividers sit between the
  * three lanes; solid edges frame the outermost lanes. */
@@ -61,15 +75,28 @@ static const u32 tile_edge[8] = {
 #define ROAD_EDGE_L    ((LANE_LEFT_X  - 12) / 8)
 #define ROAD_EDGE_R    ((LANE_RIGHT_X + 12) / 8)
 
+/* Far plane (BG_A): grass shoulders + asphalt driving surface, tiled
+ * across the whole 40x28 screen so the road no longer floats on black.
+ * Drawn at low priority; the BG_B markings + sprite cars sit on top. */
+static void draw_backdrop(void) {
+    s16 r, c;
+    for (r = 0; r < 28; r++)
+        for (c = 0; c < 40; c++) {
+            u16 t = (c >= ROAD_EDGE_L && c <= ROAD_EDGE_R) ? T_ASPHALT : T_GRASS;
+            VDP_setTileMapXY(BG_A, TILE_ATTR_FULL(PAL0, 0, 0, 0, t), c, r);
+        }
+}
+
 static void draw_road(void) {
     s16 r;
     for (r = ROAD_TOP_ROW; r <= ROAD_BOT_ROW; r++) {
-        /* Left edge (stripe on its right), right edge (hflipped). */
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_EDGE), ROAD_EDGE_L, r);
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 1, T_EDGE), ROAD_EDGE_R, r);
+        /* Left edge (stripe on its right), right edge (hflipped). HIGH
+         * priority so the markings sit above the BG_A asphalt backdrop. */
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 0, T_EDGE), ROAD_EDGE_L, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 1, T_EDGE), ROAD_EDGE_R, r);
         /* Two dashed lane dividers. */
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_LANE), LANE_DIV1_COL, r);
-        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_LANE), LANE_DIV2_COL, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 0, T_LANE), LANE_DIV1_COL, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 1, 0, 0, T_LANE), LANE_DIV2_COL, r);
     }
 }
 
@@ -125,18 +152,24 @@ static void render_score(void) {
 int main(bool hard) {
     (void)hard;
 
-    /* PAL0 = player (white + blue trim). PAL1 = enemy (red + dark). */
+    /* PAL0 = player (white + blue trim) + road backdrop. PAL1 = enemy. */
     PAL_setColor(0 + 1, 0x0EEE);    /* white body */
     PAL_setColor(0 + 2, 0x0AAA);    /* roof grey */
+    PAL_setColor(0 + 5, 0x0260);    /* roadside grass */
+    PAL_setColor(0 + 6, 0x0222);    /* asphalt grey   */
     PAL_setColor(16 + 3, 0x000E);   /* enemy red */
     PAL_setColor(16 + 4, 0x0666);   /* enemy roof */
 
-    VDP_loadTileData(tile_car_p1,    T_CAR_P1, 1, DMA);
-    VDP_loadTileData(tile_car_enemy, T_CAR_EN, 1, DMA);
-    VDP_loadTileData(tile_lane,      T_LANE,   1, DMA);
-    VDP_loadTileData(tile_edge,      T_EDGE,   1, DMA);
+    VDP_loadTileData(tile_car_p1,    T_CAR_P1,  1, DMA);
+    VDP_loadTileData(tile_car_enemy, T_CAR_EN,  1, DMA);
+    VDP_loadTileData(tile_lane,      T_LANE,    1, DMA);
+    VDP_loadTileData(tile_edge,      T_EDGE,    1, DMA);
+    VDP_loadTileData(tile_grass,     T_GRASS,   1, DMA);
+    VDP_loadTileData(tile_asphalt,   T_ASPHALT, 1, DMA);
 
-    /* Draw the static road (edges + dashed lane dividers) once on BG_B. */
+    /* Draw the grass+asphalt backdrop (BG_A) then the road markings on
+     * BG_B over it. */
+    draw_backdrop();
     draw_road();
 
     VDP_drawText("SCORE", 28, 2);

package/examples/genesis/templates/sgdk_hello.c

@@ -21,6 +21,23 @@
 
 #include <genesis.h>
 
+/* Two simple 8x8 background tiles for the far plane (BG_B). Tiling them
+ * in a checkerboard fills the whole screen so it doesn't read as a blank
+ * black backdrop. T_BG_A is a framed block (colour 1 border, colour 2
+ * fill); T_BG_B is the same block in colour 3 — alternating them gives a
+ * two-tone grid with a clear majority of non-backdrop pixels. */
+#define T_BG_A (TILE_USER_INDEX + 0)
+#define T_BG_B (TILE_USER_INDEX + 1)
+
+static const u32 tile_bg_a[8] = {
+    0x11111111, 0x12222221, 0x12222221, 0x12222221,
+    0x12222221, 0x12222221, 0x12222221, 0x11111111,
+};
+static const u32 tile_bg_b[8] = {
+    0x11111111, 0x13333331, 0x13333331, 0x13333331,
+    0x13333331, 0x13333331, 0x13333331, 0x11111111,
+};
+
 int main(bool hard) {
     /* Boot info: hard == TRUE on power-on, FALSE on soft reset (we
      * could re-init differently in each case; this minimum starter
@@ -28,7 +45,23 @@ int main(bool hard) {
     (void)hard;
 
     /* SGDK initialized the VDP + default palette in sega.s + libmd
-     * before main() ran. Just draw text. */
+     * before main() ran. We add a tiled background so the screen isn't a
+     * flat black backdrop, then draw the text on top. */
+    PAL_setColor(16 + 1, 0x0444); /* dark grey grid border */
+    PAL_setColor(16 + 2, 0x0A22); /* deep blue fill        */
+    PAL_setColor(16 + 3, 0x022A); /* deep red fill (2nd block) */
+
+    VDP_loadTileData(tile_bg_a, T_BG_A, 1, DMA);
+    VDP_loadTileData(tile_bg_b, T_BG_B, 1, DMA);
+
+    /* Fill the far plane (BG_B) with a checkerboard of the two blocks so
+     * a clear majority of the visible 40x28 cells are non-backdrop. */
+    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_BG_A : T_BG_B),
+                cx, cy);
+
     VDP_drawText("HELLO SEGA GENESIS", 10, 12);
     VDP_drawText("BUILT WITH ROM-DEV-MCP", 8, 14);
 

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/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/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);
@@ -40,17 +41,38 @@ 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. 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 +87,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 +154,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();

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;