romdevtools 0.16.0 → 0.22.0

package/examples/sms/templates/shmup.c

@@ -15,6 +15,7 @@ extern void sms_vdp_display_on(void);
 extern void sms_vdp_set_addr(uint16_t addr, uint8_t prefix);
 extern void sms_load_palette(const uint8_t *palette);
 extern void sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void sms_vblank_wait(void);
 extern uint8_t sms_joypad_read(void);
 extern void sms_sprite_init(void);
@@ -29,13 +30,49 @@ extern void sms_sat_upload(void);
 #define T_ENEMY  2
 
 static const uint8_t palette[32] = {
-  0x10,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* BG: 0 = backdrop, 1 = deep space blue, 2 = lighter space blue, 3 = star white */
+  0x10,0x08,0x20,0x3F, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
   /* Sprite palette: white, yellow, red */
   0x00,0x3F,0x0F,0x03, 0x00,0x00,0x00,0x00,
   0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
 };
 
+/* 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) */
+  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 whole 32x24 SMS screen with a banded starfield so the screen
+ * is clearly space, not a flat backdrop. BG tile bank is $0000. */
+static void draw_starfield(void) {
+  uint8_t row, col;
+  for (row = 0; row < 24; row++) {
+    for (col = 0; col < 32; col++) {
+      uint8_t t = (row & 2) ? 1 : 0;             /* alternating depth bands */
+      if (((row * 7 + col * 5) & 7) == 0) t = 2; /* sparse stars */
+      sms_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,
@@ -96,7 +133,9 @@ void main(void) {
 
   sms_vdp_init();
   sms_load_palette(palette);
-  sms_load_tiles(0x2000, sprite_tiles, 32 * 3);
+  sms_load_tiles(0x0000, bg_tiles, 96);          /* BG tiles -> BG bank $0000 */
+  sms_load_tiles(0x2000, sprite_tiles, 32 * 3);  /* sprite tiles -> $2000 */
+  draw_starfield();
 
   player.x = 120; player.y = 160; player.alive = 1;
   {

package/examples/sms/templates/shmup_2p.c

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

package/examples/sms/templates/sports.c

@@ -20,6 +20,7 @@ extern void    sms_vdp_init(void);
 extern void    sms_vdp_display_on(void);
 extern void    sms_load_palette(const uint8_t *palette);
 extern void    sms_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void    sms_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
 extern void    sms_vblank_wait(void);
 extern uint8_t sms_joypad_read(void);
 extern uint8_t sms_joypad_read_p2(void);
@@ -35,7 +36,8 @@ extern void    sms_sat_upload(void);
 #define PADDLE_X2   232
 
 static const uint8_t palette[32] = {
-  0x10, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  /* BG: 0 = backdrop, 1 = court green, 2 = court line / net white */
+  0x10, 0x08, 0x3F, 0x00, 0x00, 0x00, 0x00, 0x00,
   0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
   /* Sprite palette: white at idx 1 */
   0x00, 0x3F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
@@ -49,6 +51,43 @@ 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 (solid colour 1)
+ *   tile 1 = court line / border (solid colour 2 = white)
+ *   tile 2 = dashed net (colour 2 vertical 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 whole 32x24 court: green field, white top/bottom border lines,
+ * and a dashed net down the centre column. BG tile bank is $0000. */
+static void draw_court(void) {
+  uint8_t row, col;
+  for (row = 0; row < 24; row++) {
+    for (col = 0; col < 32; col++) {
+      uint8_t t = 0;                              /* green field          */
+      if (row <= 1 || row >= 22) t = 1;           /* white top/bottom lines */
+      else if (col == 1 || col == 30) t = 1;      /* white sidelines        */
+      else if (col == 16) t = 2;                  /* solid centre net       */
+      sms_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;
@@ -72,7 +111,9 @@ void main(void) {
   uint8_t i;
   sms_vdp_init();
   sms_load_palette(palette);
-  sms_load_tiles(0x2000, tile_solid, 32);
+  sms_load_tiles(0x0000, bg_tiles, 96);     /* BG court tiles -> BG bank $0000 */
+  sms_load_tiles(0x2000, tile_solid, 32);   /* paddle/ball sprite tile -> $2000 */
+  draw_court();
   sms_sprite_init();
   sfx_init();
   sms_vdp_display_on();
@@ -82,6 +123,7 @@ void main(void) {
   do {
     uint8_t p1, p2;
     uint8_t slot;
+    int16_t target;
     sms_vblank_wait();
     sfx_update();
 
@@ -103,12 +145,13 @@ void main(void) {
     if ((p1 & JOY_UP)   && p1y > COURT_TOP)            p1y -= 2;
     if ((p1 & JOY_DOWN) && p1y < COURT_BOT - PADDLE_H) p1y += 2;
 
-    /* P2 input if any, otherwise AI. */
+    /* P2 input if any, otherwise AI. (`target` is declared at the top of the
+     * loop body — SDCC is C89, declarations must precede statements.) */
     if (p2 != 0) {
       if ((p2 & JOY_UP)   && p2y > COURT_TOP)            p2y -= 2;
       if ((p2 & JOY_DOWN) && p2y < COURT_BOT - PADDLE_H) p2y += 2;
     } else {
-      int16_t target = by - PADDLE_H / 2;
+      target = by - PADDLE_H / 2;
       if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 1;
       else if (p2y > target && p2y > COURT_TOP)       p2y -= 1;
     }

package/examples/snes/main.asm

@@ -2,32 +2,49 @@
 ;
 ; What this does:
 ;   1. Standard SNES reset (sei, clc xce → native mode, stack at $1FFF).
-;   2. Uploads a single CGRAM color (bright blue) so you see a colored
-;      backdrop — proof your build is running. NOT just a black screen.
-;   3. Turns on the screen at full brightness, then parks forever.
+;   2. Uploads a 4-colour palette + two 2bpp tiles to VRAM via DMA.
+;   3. Fills a 32x32 BG1 tilemap with a checkerboard of those two tiles
+;      so the whole screen shows a real tiled pattern — NOT a flat one-
+;      colour backdrop (which reads as "blank" to a human / the verifier).
+;   4. Points BG1 at the tile + map bases, enables BG1, turns the screen
+;      on at full brightness, then parks forever.
 ;
-; SUFFICIENT FOR: confirming your toolchain works + your user has
-; something to see in playtest. To go further (load tiles, set up BGs,
-; sprites, sound, vblank handler) see src/platforms/snes/lib/* snippets:
+; SUFFICIENT FOR: confirming your toolchain works AND showing your user a
+; real rendered screen in playtest. To go further (sprites, scrolling,
+; sound, a vblank handler) see src/platforms/snes/lib/* snippets:
 ;
 ;   listStarterSnippets({platform:"snes"})
 ;
 ; The key snippets are:
 ;   - lorom_header.asm: full SNES header (this scaffold's is minimal)
 ;   - cgram_upload.asm: palette upload boilerplate
-;   - vram_dma_upload.asm: fast tile/map uploads
+;   - vram_dma_upload.asm: fast tile/map uploads (used below)
 ;   - oam_upload.asm: sprite table writes
 ;   - nmi_safe.asm: vblank handler skeleton
 ;
 ; BUILD: complete LoROM image, no extra options needed.
-;   build({ output: "rom",  platform: "snes", source: /* this file */ });
+;   build({ output: "run",  platform: "snes", source: /* this file */ });
 
 lorom
 
+; ── PPU / DMA registers ────────────────────────────────────────────────
 INIDISP  = $2100   ; screen brightness / forced blank
+BGMODE   = $2105   ; BG mode + tile-size
+BG1SC    = $2107   ; BG1 tilemap base + size
+BG12NBA  = $210B   ; BG1/BG2 character (tile) base
+TM       = $212C   ; main-screen layer enable
 NMITIMEN = $4200
 CGADD    = $2121
 CGDATA   = $2122
+VMAIN    = $2115   ; VRAM address increment mode
+VMADDL   = $2116   ; VRAM word address (16-bit)
+VMDATAL  = $2118   ; VRAM data port (low)
+DMAP0    = $4300   ; DMA0 control
+BBAD0    = $4301   ; DMA0 B-bus address
+A1T0L    = $4302   ; DMA0 source address (16-bit)
+A1B0     = $4304   ; DMA0 source bank
+DAS0L    = $4305   ; DMA0 byte count (16-bit)
+MDMAEN   = $420B   ; DMA enable
 
 ; -----------------------------------------------------------------------
 org $008000
@@ -40,29 +57,103 @@ START:
         txs             ; stack at $1FFF
         sep #$20        ; A = 8-bit
 
-        ; Blank screen during init.
+        ; Blank screen during init; disable NMI/HDMA.
         lda #$80
         sta INIDISP
-
-        ; Disable interrupts.
         stz NMITIMEN
 
-        ; Upload one color to CGRAM[0] (the backdrop / transparency color).
-        ; BGR-555 little-endian. $7C00 = bright blue.
+        ; ── Palette → CGRAM ───────────────────────────────────────────
+        ; 4 colours (2bpp): 0 = blue backdrop, 1 = white, 2 = green,
+        ; 3 = magenta. BGR-555, little-endian (low byte then high byte).
         stz CGADD
         lda #$00
-        sta CGDATA
+        sta CGDATA          ; colour 0 low  ($7C00 = blue)
+        lda #$7C
+        sta CGDATA          ; colour 0 high
+        lda #$FF
+        sta CGDATA          ; colour 1 low  ($7FFF = white)
+        lda #$7F
+        sta CGDATA          ; colour 1 high
+        lda #$E0
+        sta CGDATA          ; colour 2 low  ($03E0 = green)
+        lda #$03
+        sta CGDATA          ; colour 2 high
+        lda #$1F
+        sta CGDATA          ; colour 3 low  ($7C1F = magenta)
         lda #$7C
-        sta CGDATA
+        sta CGDATA          ; colour 3 high
+
+        ; ── Tile CHR → VRAM word $0000 (DMA channel 0) ────────────────
+        ; Two 8x8 2bpp tiles = 32 bytes. VMAIN $80 = +1 word after the
+        ; high-byte write; B-bus $18 = VMDATAL (auto-alternates to $2119).
+        ldx #$0000
+        stx VMADDL
+        lda #$80
+        sta VMAIN
+        lda #$01
+        sta DMAP0           ; DMA mode 1 (2 regs, word transfers)
+        lda #$18
+        sta BBAD0           ; → $2118 / $2119
+        ldx #TILES
+        stx A1T0L
+        lda #TILES>>16
+        sta A1B0
+        ldx #(TILES_END-TILES)
+        stx DAS0L           ; byte count
+        lda #$01
+        sta MDMAEN          ; fire channel 0
+
+        ; ── Fill BG1 tilemap → VRAM word $0400 (byte $0800) ───────────
+        ; A 32x32 map = 1024 entries. Each entry is a word: low byte =
+        ; tile index, high byte = attributes (0). We write a checkerboard
+        ; of tile 0 / tile 1 directly through the data port (no source
+        ; buffer needed). VMAIN already = +1 word per write.
+        ldx #$0400
+        stx VMADDL
+        rep #$20            ; A = 16-bit for word writes
+        ldy #$0000          ; entry counter (0..1023)
+.maploop:
+        tya
+        and #$0001          ; checker by column parity
+        sta VMDATAL         ; entry = tile 0 or tile 1
+        iny
+        cpy #1024
+        bne .maploop
+        sep #$20            ; back to 8-bit A
 
-        ; Enable screen at full brightness (bit 7 = 0 to disable forced
-        ; blank; low nybble = brightness 0..15).
+        ; ── BG1 base registers ────────────────────────────────────────
+        stz BGMODE          ; mode 0, 8x8 tiles
+        ; BG1SC: bits 2-7 = tilemap base in $0400-word units, bits 0-1 =
+        ; size (00 = 32x32). Map is at word $0400 → base = 1 → ($01<<2)=$04.
+        lda #$04
+        sta BG1SC
+        stz BG12NBA         ; BG1 char base = word $0000 (our tiles)
+        lda #$01
+        sta TM              ; enable BG1 on the main screen
+
+        ; ── Screen ON at full brightness ──────────────────────────────
         lda #$0F
         sta INIDISP
 
 LOOP:
         bra LOOP
 
+; -----------------------------------------------------------------------
+; Tile CHR: two 8x8 2bpp tiles (16 bytes each). 2bpp = 2 bitplanes
+; interleaved per row: byte0=row0 plane0, byte1=row0 plane1, ...
+;
+; Tile 0 — solid colour 1 (plane0 all set, plane1 clear → colour 1).
+; Tile 1 — checker of colour 2 / colour 3 (both planes patterned) so the
+; map's alternating tiles give a busy, multi-colour screen.
+TILES:
+; tile 0 (solid: every pixel colour 1)
+db $FF, $00, $FF, $00, $FF, $00, $FF, $00
+db $FF, $00, $FF, $00, $FF, $00, $FF, $00
+; tile 1 (checkerboard: colour 2 / colour 3 alternating per pixel)
+db $AA, $55, $55, $AA, $AA, $55, $55, $AA
+db $AA, $55, $55, $AA, $AA, $55, $55, $AA
+TILES_END:
+
 ; -----------------------------------------------------------------------
 ; Emulation-mode reset vector (used at boot, before `xce` flips to native).
 ; asar's `lorom` directive handles header + rest of vector table padding.

package/examples/snes/templates/c-hello-data.asm

@@ -320,4 +320,27 @@ palfont:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00
 
+
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; backdrop never reads as flat/blank. Quadrant->colour: TL=1, TR=2, BL=3,
+; BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1 pairs, bytes
+; 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/c-hello.c

@@ -27,13 +27,20 @@
 #include <snes.h>
 
 extern char tilfont, palfont;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * It has no public prototype in console.h, so declare it here. Call it
  * once per frame (after WaitForVBlank) or via nmiSet(consoleVblank). */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * screen never reads as a flat/blank backdrop. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
+    u16 i;
+
     /* ── 1. PVSnesLib text-mode setup ─────────────────────────────
      * Map + tile-data + palette-offset addresses are conventions —
      * any free VRAM region will work, these match PVSnesLib's
@@ -54,7 +61,17 @@ int main(void) {
     setMode(BG_MODE1, 0);
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the screen never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of the console gfx
+     * $3000 / map $6800). Map entries use palette block 1 (0x0400) so the
+     * wallpaper palette doesn't disturb the console font palette in block 0
+     * (HUD text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     /* ── 3. Draw text ─────────────────────────────────────────────

package/examples/snes/templates/default.c

@@ -1,61 +1,83 @@
 /* default.c — SNES PVSnesLib starter (C).
  *
- * Smallest "ROM that does something visible" — sets a blue backdrop
- * and parks a white diamond sprite in the centre of the screen.
- * Pressing the d-pad moves the sprite.
+ * Smallest "ROM that does something visible": a full-screen diamond-tile
+ * background (BG0) with a movable white sprite parked in the centre.
+ * Pressing the d-pad moves the sprite. The tiled backdrop means the very
+ * first build shows recognizable content, not a flat colour — the SNES
+ * equivalent of the "is anything even rendering?" smoke test.
  *
  * Picked as the default SNES template because:
- *   - PVSnesLib gives a clean C API (oamSet, padsCurrent, etc.)
+ *   - PVSnesLib gives a clean C API (bgInitTileSet, oamSet, padsCurrent…)
  *     instead of raw 65816 / direct register pokes.
  *   - tcc-65816 builds it in <2s.
- *   - You read this file once and know how every SNES C scaffold
- *     is structured (hello_sprite, shmup, platformer all extend it).
+ *   - You read this file once and know how every SNES C scaffold is
+ *     structured (hello_sprite, shmup, platformer all extend it).
+ *
+ * The one footgun this guards against: on the SNES, NOTHING renders until
+ * setScreenOn() lifts forced blank (INIDISP $80) AND at least one layer
+ * (a BG or the sprite layer) actually has tiles + a non-black palette.
+ * Disabling every BG and showing one sprite (the obvious "minimal" move)
+ * leaves a near-blank screen — so here we light up BG0 too.
  *
- * For raw 65816 see template:"asm" (kept for cycle-accurate work).
  * For text-mode console output see template:"c_hello".
- * For genre-shaped scaffolds see createGame({genre:"shmup", ...}).
+ * For raw 65816 see template:"asm" (kept for cycle-accurate work).
+ * For genre-shaped scaffolds see scaffold({op:'game', genre:"shmup", ...}).
  *
- * Sibling `data.asm` provides the sprite tile + palette bytes.
- * Build:
- *   build({ output: "rom", 
- *     platform:"snes", language:"c",
- *     sourcesPaths:{"main.c":"...","data.asm":"..."},
- *   })
+ * Sibling `data.asm` provides tilsprite (one 8×8 4bpp diamond tile) +
+ * palsprite (its 16-colour palette). We reuse that one tile for BOTH the
+ * sprite and the BG wallpaper — replace with real gfx4snes .pic/.pal art.
  */
 #include <snes.h>
 
 extern char tilsprite, palsprite;
 
+/* A 32×32 BG tilemap (one screen), all pointing at tile 0 = the diamond.
+ * SNES map entries are 16-bit (tile# + palette/priority/flip bits); 0x0000
+ * = tile 0, palette 0, no flip. 32*32 = 1024 entries = 2048 bytes. We fill
+ * it at runtime so the source stays small. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
     u16 x = 120, y = 100;
+    u16 i;
 
-    /* BG_MODE1 with all BG layers disabled — we render only the
-     * sprite layer on top of the backdrop colour. */
+    /* BG_MODE1: BG0/BG1 are 16-colour, BG2 is 4-colour — standard mix.
+     * We use BG0 for the wallpaper and the sprite layer on top. */
     setMode(BG_MODE1, 0);
-    bgSetDisable(0);
     bgSetDisable(1);
     bgSetDisable(2);
 
-    /* Backdrop colour (CGRAM entry 0). RGB5: red=0, green=0, blue=15
-     * → bright SNES blue. setPaletteColor packs to BGR555 for us. */
-    setPaletteColor(0, RGB5(0, 0, 15));
+    /* Load the diamond tile + its palette as BG0's tileset. Tile gfx go to
+     * VRAM $2000, palette into BG palette 0. 32 bytes of tile (one 8×8 4bpp
+     * tile), 32 bytes of palette (16 colours × 2). */
+    bgInitTileSet(0, (u8 *)&tilsprite, (u8 *)&palsprite,
+                  0,            /* palette entry 0 */
+                  32,           /* tile data size  */
+                  32,           /* palette size    */
+                  BG_16COLORS,  /* colour mode     */
+                  0x2000);      /* VRAM addr for BG0 tiles */
+
+    /* Fill the map with tile 0 and upload it to VRAM $6000. */
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0000;
+    bgInitMapSet(0, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x6000);
+
+    bgSetEnable(0);
 
-    /* Upload 32 bytes of sprite tile + 32 bytes of sprite palette to
-     * VRAM $0000 / OBJ palette slot 0. OBJ_SIZE8_L16 = small sprites
-     * are 8×8, large 16×16 (we use small). */
+    /* Upload the same tile as a sprite (VRAM $0000, OBJ palette slot 0) so
+     * the movable sprite reads distinctly on top of the wallpaper. */
     oamInitGfxSet(&tilsprite, 32, &palsprite, 32,
                   0,              /* OBJ palette slot */
                   0x0000,         /* VRAM address for sprite tiles */
                   OBJ_SIZE8_L16);
 
-    /* Place sprite #0 at the centre. */
+    /* Place sprite #0 at the centre, highest priority so it sits over BG0. */
     oamSet(0, x, y,
-           3 /* highest priority */,
-           0 /* no flip */, 0 /* palette */, 0 /* tile index */, 0 /* objsize */);
+           3 /* priority */, 0 /* no flip */, 0 /* palette */,
+           0 /* tile index */, 0 /* objsize */);
     oamSetEx(0, OBJ_SMALL, OBJ_SHOW);
 
-    /* Until setScreenOn() fires, the SNES holds forced blank
-     * (INIDISP $80) and nothing renders. */
+    /* Until setScreenOn() fires, the SNES holds forced blank (INIDISP $80)
+     * and nothing renders. */
     setScreenOn();
 
     while (1) {

package/examples/snes/templates/hello_sprite-data.asm

@@ -340,4 +340,27 @@ palsprite:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00, $00, $00, $00, $00, $00, $00
 
+
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; backdrop never reads as flat/blank. Quadrant->colour: TL=1, TR=2, BL=3,
+; BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1 pairs, bytes
+; 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends

package/examples/snes/templates/hello_sprite.c

@@ -24,14 +24,20 @@
 
 extern char tilfont, palfont;
 extern char tilsprite, palsprite;
+extern char tilbg, palbg;       /* wallpaper tile + palette (data.asm) */
 
 /* consoleVblank() copies the dirty text tilemap to VRAM during VBlank.
  * No public prototype in console.h, so declare it; call once per frame. */
 extern void consoleVblank(void);
 
+/* BG1 wallpaper map: a full 32x32 screen of the 4-colour tile so the
+ * screen never reads as a flat/blank backdrop. Filled at runtime. */
+static u16 bg_map[32 * 32];
+
 int main(void) {
     u16 x = 120, y = 100;
     u16 prev = 0;
+    u16 i;
 
     /* Text setup — same layout as c-hello. */
     consoleSetTextMapPtr(0x6800);
@@ -44,7 +50,17 @@ int main(void) {
      * registers — point BG0 at the same font ($3000) + map ($6800). */
     bgSetGfxPtr(0, 0x3000);
     bgSetMapPtr(0, 0x6800, SC_32x32);
-    bgSetDisable(1);
+
+    /* BG1 = full-screen wallpaper so the screen never reads as blank.
+     * Tiles -> VRAM $2000, map -> VRAM $4000 (clear of sprites $0000 and
+     * the console gfx $3000 / map $6800). Map entries use palette block 1
+     * (0x0400) so the wallpaper palette doesn't disturb the console font
+     * palette in block 0 (status text stays legible). */
+    bgInitTileSet(1, (u8 *)&tilbg, (u8 *)&palbg, 1,
+                  32, 32, BG_16COLORS, 0x2000);
+    for (i = 0; i < 32 * 32; i++) bg_map[i] = 0x0400;
+    bgInitMapSet(1, (u8 *)bg_map, sizeof(bg_map), SC_32x32, 0x4000);
+    bgSetEnable(1);
     bgSetDisable(2);
 
     /* OAM init — sprite tiles at VRAM $0000, 8x8 default. */

package/examples/snes/templates/music_demo-data.asm

@@ -315,4 +315,27 @@ palfont:
 .db $00, $00, $00, $00, $00, $00, $00, $00
 .db $00, $00
 
+
+; ── Background wallpaper (one 8x8 4bpp tile, 4 solid colour quadrants) ──
+; Tiled across BG1 it paints the whole screen in four muted colours so the
+; backdrop never reads as flat/blank. Quadrant->colour: TL=1, TR=2, BL=3,
+; BR=4. 4bpp plane order: bytes 0-15 = rows 0-7 plane0/plane1 pairs, bytes
+; 16-31 = rows 0-7 plane2/plane3 pairs.
+tilbg:
+.db $F0, $0F, $F0, $0F, $F0, $0F, $F0, $0F   ; rows 0-3: p0=left  p1=right
+.db $F0, $F0, $F0, $F0, $F0, $F0, $F0, $F0   ; rows 4-7: p0+p1 = left
+.db $00, $00, $00, $00, $00, $00, $00, $00   ; rows 0-3: p2/p3 = 0
+.db $0F, $00, $0F, $00, $0F, $00, $0F, $00   ; rows 4-7: p2 = right
+
+palbg:
+; 16-colour BG palette; only 1-4 used (the four wallpaper quadrant tones).
+.db $00, $00          ; 0 unused (BG fully opaque)
+.db $C4, $30          ; 1 dark blue
+.db $42, $29          ; 2 dark teal
+.db $88, $30          ; 3 dark purple
+.db $C6, $24          ; 4 dark slate
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00, $00, $00
+.db $00, $00, $00, $00, $00, $00
+
 .ends