romdevtools 0.21.0 → 0.22.0

package/examples/gba/templates/maxmod_demo.c

@@ -47,6 +47,19 @@ extern const u8 soundbank_bin[];
  * Adjust if you regenerate with a differently-named .xm. */
 #define MOD_CHIPTUNE 0
 
+/* ── Backdrop tiles (4bpp) ───────────────────────────────────────────
+ * Two solid-colour tiles so we can lay a two-tone checkerboard across the
+ * whole BG1 map. Without a filled backdrop the screen is just the black
+ * backdrop colour plus a few text glyphs — which reads as "blank". */
+static const u32 tile_solid1[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+static const u32 tile_solid2[8] = {
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+};
+
 int main(void) {
     /* ── IRQ setup ── Maxmod requires mmVBlank() in the VBlank slot.
      * Without this, the mixer DMA buffers never get swapped and audio
@@ -55,9 +68,30 @@ int main(void) {
     irq_init(NULL);
     irq_add(II_VBLANK, mmVBlank);
 
-    /* TTE setup so we can show a status banner. Standard Tonc setup. */
+    /* ── Filled checkerboard backdrop on BG1 ─────────────────────────
+     * Lay a two-tone checkerboard across the whole 32x32 BG1 map so the
+     * frame has real content behind the text instead of a flat black
+     * backdrop (which reads as "blank"). Tiles → char-block 1, map →
+     * screen-block 28 — clear of TTE's char-block 0 / screen-block 31. */
+    pal_bg_mem[0] = CLR_BLACK;
+    pal_bg_mem[1] = RGB15(3, 6, 14);   /* deep sky blue */
+    pal_bg_mem[2] = RGB15(2, 4, 9);    /* darker navy   */
+    tonccpy(&tile_mem[1][1], tile_solid1, sizeof(tile_solid1));
+    tonccpy(&tile_mem[1][2], tile_solid2, sizeof(tile_solid2));
+    REG_BG1CNT = BG_CBB(1) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(3);
+    {
+        SCR_ENTRY *map = se_mem[28];
+        int tx, ty;
+        for (ty = 0; ty < 32; ty++)
+            for (tx = 0; tx < 32; tx++)
+                map[ty * 32 + tx] = SE_BUILD(1 + ((tx ^ ty) & 1), 0, 0, 0);
+    }
+
+    /* TTE setup so we can show a status banner. Standard Tonc setup.
+     * TTE text on BG0 in front of the BG1 backdrop. */
     tte_init_chr4c_default(0, BG_CBB(0) | BG_SBB(31));
-    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0;
+    REG_BG0CNT |= BG_PRIO(0);          /* text in front of the backdrop */
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_BG1;
 
     tte_write("#{P:24,32}");
     tte_write("Maxmod demo");

package/examples/gba/templates/platformer.c

@@ -45,7 +45,9 @@ static const Rect platforms[] = {
     { 440, 120,  56,   8 },
     { 180,  52,  48,   8 },
 };
-#define N_PLATFORMS (sizeof(platforms) / sizeof(platforms[0]))
+/* (int) cast so `for (int i = 0; i < N_PLATFORMS; ...)` doesn't compare a
+ * signed counter against an unsigned size_t (-Wsign-compare). */
+#define N_PLATFORMS ((int)(sizeof(platforms) / sizeof(platforms[0])))
 
 static OBJ_ATTR obj_buffer[128];
 

package/examples/gba/templates/tonc_hello_sprite.c

@@ -35,6 +35,19 @@ static const u32 sprite_tile[8] = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
 };
 
+/* ── Backdrop tiles (4bpp) ───────────────────────────────────────────
+ * Two solid-colour BG tiles so we can lay a two-tone checkerboard across
+ * the whole BG0 map. Without a filled backdrop the screen is just the
+ * black backdrop colour and one tiny sprite — which reads as "blank". */
+static const u32 bg_tile1[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+static const u32 bg_tile2[8] = {
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+    0x22222222, 0x22222222, 0x22222222, 0x22222222,
+};
+
 /* Shadow OAM. Tonc's recommended pattern: allocate your own 128-slot
  * buffer in WRAM, mutate it freely each frame, then oam_copy to push
  * the changes to OAM hardware via DMA. */
@@ -81,12 +94,33 @@ int main(void) {
         ATTR2_PALBANK(0) | 0);
     obj_set_pos(&obj_buffer[0], x, y);
 
+    /* ── Filled checkerboard backdrop on BG0 ─────────────────────
+     * Lay a two-tone checkerboard across the whole 32x32 BG0 map so the
+     * frame has real content behind the sprite instead of a flat black
+     * backdrop (which reads as "blank"). BG tiles → char-block 0, map →
+     * screen-block 28 (the OBJ tiles live in char-block 4, so there's no
+     * clash). */
+    pal_bg_mem[0] = CLR_BLACK;
+    pal_bg_mem[1] = RGB15(3, 6, 14);   /* deep sky blue */
+    pal_bg_mem[2] = RGB15(2, 4, 9);    /* darker navy   */
+    tonccpy(&tile_mem[0][1], bg_tile1, sizeof(bg_tile1));
+    tonccpy(&tile_mem[0][2], bg_tile2, sizeof(bg_tile2));
+    REG_BG0CNT = BG_CBB(0) | BG_SBB(28) | BG_REG_32x32 | BG_4BPP | BG_PRIO(3);
+    {
+        SCR_ENTRY *map = se_mem[28];
+        int tx, ty;
+        for (ty = 0; ty < 32; ty++)
+            for (tx = 0; tx < 32; tx++)
+                map[ty * 32 + tx] = SE_BUILD(1 + ((tx ^ ty) & 1), 0, 0, 0);
+    }
+
     /* ── Display setup ───────────────────────────────────────────
      * DCNT_MODE0  — tiled mode (so BG0..3 are tile maps)
+     * DCNT_BG0    — enable the checkerboard backdrop
      * DCNT_OBJ    — enable sprites
      * DCNT_OBJ_1D — linear OAM tile addressing (vs the 2D matrix
      *               layout that's almost always wrong) */
-    REG_DISPCNT = DCNT_MODE0 | DCNT_OBJ | DCNT_OBJ_1D;
+    REG_DISPCNT = DCNT_MODE0 | DCNT_BG0 | DCNT_OBJ | DCNT_OBJ_1D;
 
     /* ── Game loop ───────────────────────────────────────────────
      * key_poll() updates the key state — call it once per frame.

package/examples/gbc/templates/hello_sprite.c

@@ -54,6 +54,8 @@ void main(void) {
   uint8_t x = 80;       /* hardware X = screen X + 8 */
   uint8_t y = 80;       /* hardware Y = screen Y + 16 */
   uint8_t i;
+  uint8_t *bg_map;
+  uint16_t j;
 
   /* ── 1. LCD off (safe whether it was on or off) ──────────────────
    * lcd_init_default() checks LCDC.7 and only waits for vblank if the
@@ -71,6 +73,13 @@ void main(void) {
    * TROUBLESHOOTING.md "VRAM stays empty / sprite never appears". */
   memcpy_vram((uint8_t *)0x8010, tile_data, 16);
 
+  /* ── 2b. Fill the BG tilemap so the screen isn't an empty backdrop. ──
+   * With LCDC_TILE_DATA_LO ($8000 addressing) BG tile index 1 == our tile
+   * at $8010 — so we tile the whole 32×32 BG map with it. Pointer-walk write
+   * (NOT bg_map[k]=1, which SDCC sm83 miscompiles into VRAM). */
+  bg_map = (uint8_t *)0x9800;
+  for (j = 0; j < 32u * 32u; j++) *bg_map++ = 1;
+
   /* ── 3. Object palette 0 (CGB path) ──────────────────────────────
    * OCPS bit 7 = auto-increment after each write; bits 5..3 = palette
    * index (0..7); bits 2..1 = color index (0..3); bit 0 = MSB select.
@@ -102,9 +111,9 @@ void main(void) {
   oam_dma_flush();
 
   /* ── 5. Turn the LCD back on with BG + OBJ enabled. ──────────────
-   * LCDC bits: 0x80=LCD on, 0x02=OBJ on, 0x10=tile data at $8000.
-   * (BG remains off — we have no BG map set up.) */
-  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+   * LCDC bits: 0x80=LCD on, 0x01=BG on, 0x02=OBJ on, 0x10=tile data at $8000.
+   * BG is on now that we filled the BG map in step 2b. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
 
   /* ── 6. APU on — let the player beep ──────────────────────────── */
   sound_init();

package/examples/gbc/templates/music_demo.c

@@ -23,6 +23,9 @@
 
 extern const huge_song_t sample_song;
 
+/* CGB BG palette 0: backdrop colour cycles (bg_colors[shade]) while
+ * colours 1..3 stay fixed and bright, so the checkerboard backdrop below
+ * always shows several distinct colours (not a single flat field). */
 static const uint16_t bg_colors[4] = {
   0x4210,  /* dim purple */
   0x4308,  /* dim blue   */
@@ -30,21 +33,66 @@ static const uint16_t bg_colors[4] = {
   0x0017,  /* dim red    */
 };
 
+/* Two 8×8 2bpp tiles so the BG isn't a single flat colour:
+ *   tile 1 — solid colour 1
+ *   tile 2 — solid colour 2
+ * Checkerboarded across the BG map below. */
+static const uint8_t tile_solid1[16] = {
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+  0xFF,0x00, 0xFF,0x00, 0xFF,0x00, 0xFF,0x00,
+};
+static const uint8_t tile_solid2[16] = {
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+  0x00,0xFF, 0x00,0xFF, 0x00,0xFF, 0x00,0xFF,
+};
+
+/* Write CGB BG palette 0 with the current backdrop shade plus fixed bright
+ * colours 1..3 (blue / green / white) so the checkerboard is multi-colour. */
+static void set_bg_palette(uint8_t shade) {
+  BCPS = 0x80;            /* auto-increment, start at palette 0 colour 0 */
+  /* colour 0 — animated backdrop */
+  BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
+  BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
+  /* colour 1 — bright blue */
+  BCPD = (uint8_t)(0x7C00u & 0xFFu);
+  BCPD = (uint8_t)((0x7C00u >> 8) & 0xFFu);
+  /* colour 2 — bright green */
+  BCPD = (uint8_t)(0x03E0u & 0xFFu);
+  BCPD = (uint8_t)((0x03E0u >> 8) & 0xFFu);
+  /* colour 3 — white */
+  BCPD = (uint8_t)(0x7FFFu & 0xFFu);
+  BCPD = (uint8_t)((0x7FFFu >> 8) & 0xFFu);
+}
+
 void main(void) {
-  uint8_t  i;
   uint8_t  shade = 0;
   uint16_t frame = 0;
+  uint8_t *bg_map;
+  uint16_t j;
 
   lcd_init_default();
-  sound_init();
+  LCDC = 0;               /* LCD off so we can write VRAM freely */
 
-  /* Write the initial CGB BG palette 0 (4 entries, same colour). */
-  BCPS = 0x80;            /* auto-increment, start at index 0 */
-  for (i = 0; i < 4; i++) {
-    BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
-    BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
+  /* Upload two tiles to VRAM slots 1 ($8010) and 2 ($8020). Use
+   * memcpy_vram (pointer-walk) — an indexed dst[i]=src[i] loop into VRAM
+   * is miscompiled by SDCC sm83. */
+  memcpy_vram((uint8_t *)0x8010, tile_solid1, 16);
+  memcpy_vram((uint8_t *)0x8020, tile_solid2, 16);
+
+  /* Checkerboard the 32×32 BG map at $9800 with tiles 1 and 2. Pointer-walk
+   * (NOT bg_map[k]=..., which SDCC sm83 miscompiles into VRAM). */
+  bg_map = (uint8_t *)0x9800;
+  for (j = 0; j < 32u * 32u; j++) {
+    *bg_map++ = (uint8_t)((((j ^ (j >> 5)) & 1u) ? 1u : 2u));
   }
 
+  set_bg_palette(shade);
+
+  /* LCD on with BG enabled, $8000 tile-data addressing. */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_TILE_DATA_LO;
+
+  sound_init();
+
   hUGE_init(&sample_song);
 
   for (;;) {
@@ -53,11 +101,7 @@ void main(void) {
     frame++;
     if ((frame & 0x3F) == 0) {     /* every 64 frames ≈ 1 s */
       shade = (uint8_t)((shade + 1) & 0x03);
-      BCPS = 0x80;
-      for (i = 0; i < 4; i++) {
-        BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
-        BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
-      }
+      set_bg_palette(shade);
     }
   }
 }

package/examples/gbc/templates/platformer.c

@@ -78,8 +78,9 @@ static uint8_t on_platform(int16_t px, int16_t py) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
     uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-    uint8_t i;
-    for (i = 0; i < 16; i++) dst[i] = src[i];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
 }
 
 static void paint_platforms(void) {

package/examples/gbc/templates/puzzle.c

@@ -141,8 +141,9 @@ static void lock_piece(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
     uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-    uint8_t i;
-    for (i = 0; i < 16; i++) dst[i] = src[i];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
 }
 
 /* Draw the well frame around the 6×12 play area. Grid cells live at

package/examples/gbc/templates/racing.c

@@ -114,8 +114,9 @@ static void spawn_obstacle(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
   uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-  uint8_t i;
-  for (i = 0; i < 16; i++) dst[i] = src[i];
+  /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+  memcpy_vram(dst, src, 16);
 }
 
 /* Paint the road into BG map 0 ($9800). 20×18 visible cells:

package/examples/gbc/templates/shmup.c

@@ -108,8 +108,9 @@ static void spawn(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
     uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-    uint8_t i;
-    for (i = 0; i < 16; i++) dst[i] = src[i];
+    /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+     * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+    memcpy_vram(dst, src, 16);
 }
 
 /* Paint a starfield into BG map 0 ($9800): fill the visible 20×18 with the

package/examples/gbc/templates/sports.c

@@ -79,8 +79,9 @@ static void reset_match(void) {
 
 static void upload_tile(uint8_t slot, const uint8_t *src) {
   uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
-  uint8_t i;
-  for (i = 0; i < 16; i++) dst[i] = src[i];
+  /* memcpy_vram (pointer-walk) — NOT an indexed dst[i]=src[i] loop, which
+   * SDCC sm83 miscompiles when dst points into VRAM ($8000-$9FFF). */
+  memcpy_vram(dst, src, 16);
 }
 
 /* Paint the Pong court into BG map 0 ($9800): dithered turf everywhere,

package/examples/gbc/templates/tile_engine.c

@@ -143,8 +143,9 @@ static const uint8_t rooms[ROOMS][ROWS * COLS] = {
 
 /* ── Helpers ────────────────────────────────────────────────────── */
 static void copy_to_vram(uint8_t *dst, const uint8_t *src, uint16_t n) {
-  uint16_t i;
-  for (i = 0; i < n; i++) dst[i] = src[i];
+  /* Delegate to the runtime's pointer-walk copy — an indexed dst[i]=src[i]
+   * loop into VRAM is miscompiled by SDCC sm83. */
+  memcpy_vram(dst, src, n);
 }
 
 static void load_bg_palette(void) {

package/examples/genesis/main.s

@@ -89,7 +89,7 @@ Start:
         move.w  #$0000,VDP_DATA      ; color 0: transparent / backdrop
         move.w  #$0EEE,VDP_DATA      ; color 1: white-ish ($0E in each nybble)
         move.w  #$00EE,VDP_DATA      ; color 2: yellow
-        move.w  #$0E00,VDP_DATA      ; color 3: blue (unused)
+        move.w  #$0840,VDP_DATA      ; color 3: dark teal (backdrop fill)
 
         ; -----------------------------------------------------------
         ; Upload one 4bpp tile (8x8 'H', color 2 = yellow) to VRAM at
@@ -104,6 +104,34 @@ Start:
         move.l  (a1)+,VDP_DATA       ; each row = one longword (4 bytes)
         dbra    d0,.tile_loop
 
+        ; -----------------------------------------------------------
+        ; Upload two PATTERNED backdrop tiles (#2 and #3) to VRAM at
+        ; byte offsets $40 and $60 (VRAM cmd $40400000). Each is a teal
+        ; (color 3) field sprinkled with white (color 1) dots, with the
+        ; roles swapped between the two so that when we checkerboard them
+        ; across the plane no single colour dominates the screen — a
+        ; uniform fill still reads as "blank" to a human, so we vary it.
+        ; 16 longwords total (8 rows × 2 tiles) written back-to-back.
+        move.l  #$40400000,VDP_CTRL
+        lea     TileBgA(pc),a1
+        moveq   #16-1,d0             ; 8 rows × 2 tiles
+.bg_tile_loop:
+        move.l  (a1)+,VDP_DATA
+        dbra    d0,.bg_tile_loop
+
+        ; -----------------------------------------------------------
+        ; Fill the ENTIRE plane A name table, checkerboarding tiles #2
+        ; and #3 so there's a varied visible background behind the 'H'.
+        ; Plane A base is $C000; plane size is 64x32 = 2048 cells. VRAM
+        ; write at $C000 = cmd $40000003. d1 toggles 2↔3 each cell.
+        move.l  #$40000003,VDP_CTRL
+        move.w  #2048-1,d0           ; 2048 cells to write
+        moveq   #2,d1               ; start with tile #2
+.bg_fill_loop:
+        move.w  d1,VDP_DATA          ; tile d1 (pal 0, no flip, low pri)
+        eor.w   #$0001,d1            ; toggle 2↔3 (tile index xor 1)
+        dbra    d0,.bg_fill_loop
+
         ; -----------------------------------------------------------
         ; Place tile #1 in plane A near screen center.
         ; Plane A base is at VRAM $C000 (default after VDP init).
@@ -159,3 +187,27 @@ TileH:
         dc.l    $20000020
         dc.l    $20000020
         dc.l    $00000000       ; row 7: blank
+
+; -----------------------------------------------------------------------
+; Two patterned backdrop tiles, 4bpp, uploaded back-to-back as #2 and #3.
+; TileBgA = teal (color 3) field with white (color 1) dots; TileBgB swaps
+; the roles (white field, teal dots). Checkerboarding them across the
+; plane keeps any single colour well under the "blank" threshold.
+TileBgA:                         ; tile #2 — teal field, white dots
+        dc.l    $33333333
+        dc.l    $33133313
+        dc.l    $33333333
+        dc.l    $13333331
+        dc.l    $33333333
+        dc.l    $33133313
+        dc.l    $33333333
+        dc.l    $13333331
+TileBgB:                         ; tile #3 — white field, teal dots
+        dc.l    $11111111
+        dc.l    $11311131
+        dc.l    $11111111
+        dc.l    $31111113
+        dc.l    $11111111
+        dc.l    $11311131
+        dc.l    $11111111
+        dc.l    $31111113

package/examples/genesis/templates/hello_sprite.c

@@ -29,6 +29,17 @@ static const u32 tile_data[8] = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
 };
 
+/* A checkered backdrop block tiled across plane B so the screen isn't a
+ * flat black void (a lone sprite on black reads as "blank" to a human).
+ * Colour index 4 with a thin colour-5 frame — we set both below. */
+static const u32 tile_bg[8] = {
+    0x44444444, 0x45555554, 0x45000054, 0x45000054,
+    0x45000054, 0x45000054, 0x45555554, 0x44444444,
+};
+
+#define T_SPRITE (TILE_USER_INDEX + 0)
+#define T_BG     (TILE_USER_INDEX + 1)
+
 int main(bool hard) {
     (void)hard;
 
@@ -38,11 +49,22 @@ int main(bool hard) {
 
     /* Make sure sprite palette 0 entry 1 is white so we can see our
      * tile. SGDK uses 0RRR0GGG0BBB packed words (BGR, 3 bits each). */
-    PAL_setColor(1, 0x0EEE); /* near-white */
+    PAL_setColor(1, 0x0EEE); /* near-white sprite */
+    /* Plane-B backdrop colours (palette 1). */
+    PAL_setColor(16 + 4, 0x0640); /* dark teal field */
+    PAL_setColor(16 + 5, 0x0860); /* lighter frame   */
 
     /* Upload the user tile to VRAM at TILE_USER_INDEX (everything
      * below that is reserved for SGDK's font + system tiles). */
-    VDP_loadTileData(tile_data, TILE_USER_INDEX, 1, DMA);
+    VDP_loadTileData(tile_data, T_SPRITE, 1, DMA);
+    VDP_loadTileData(tile_bg,   T_BG,     1, DMA);
+
+    /* Tile plane B with the backdrop block so there's a visible
+     * background behind the sprite + text. Sprites + the font plane (A)
+     * always draw above plane B, so the d-pad sprite reads on top. */
+    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);
 
     VDP_drawText("D-PAD MOVES THE SPRITE", 8, 2);
     VDP_drawText("START FOR SOFT RESET",  9, 4);
@@ -66,7 +88,7 @@ int main(bool hard) {
          * SPRITE_SIZE(1,1) = 8×8. TILE_ATTR_FULL(palette,prio,vflip,
          * hflip,tile_index). */
         VDP_setSprite(0, px, py, SPRITE_SIZE(1, 1),
-                      TILE_ATTR_FULL(PAL0, 0, 0, 0, TILE_USER_INDEX));
+                      TILE_ATTR_FULL(PAL0, 1, 0, 0, T_SPRITE));
         VDP_updateSprites(1, DMA);
 
         SYS_doVBlankProcess();

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/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();