romdevtools 0.16.0 → 0.22.0

package/examples/msx/shmup/main.c

@@ -0,0 +1,288 @@
+/* ── shmup/main.c — MSX vertical-shooter scaffold (screen 2) ─────────
+ *
+ * Mirrors the NES/Genesis/SNES/GB/SMS shmup scaffolds, translated to the
+ * MSX VDP via the romdev MSX helper lib (msx_hw.h + msx_vdp.c).
+ *
+ * Player ship (sprite plane 0) + 4 bullet slots (planes 1-4) + 4 enemy
+ * slots (planes 5-8), a wave spawner, and AABB collisions. Score is drawn
+ * as on-screen tiles ("SCORE 000") along the top row. The whole 32x24
+ * screen-2 name table is painted with a banded starfield so the display is
+ * clearly space, not a flat backdrop.
+ *
+ * Controls: joystick LEFT/RIGHT/UP/DOWN moves the ship, trigger A fires.
+ *   We read joystick PORT 1 (and the keyboard cursor on stick 0 as a
+ *   fallback), and GTTRIG for the fire button.
+ *
+ * Cartridge rule: INIT must never return, so main() ends in for(;;).
+ *
+ * Hardware path (all through the MSX helper lib):
+ *   - msx_set_screen2()    screen 2 (GRAPHIC II), 256x192, display ON
+ *   - msx_vram_write()     upload tile font + sprite patterns to VRAM
+ *   - msx_set_sprite()     position the ship/bullets/enemies each frame
+ *   - msx_read_joystick()  BIOS GTSTCK — 0=center, 1-8 = direction CW
+ *   - msx_psg_tone/off()   fire blip + explosion noise
+ *   - vsync()              one game step per VDP frame (interrupt-free)
+ */
+#include "msx_hw.h"
+
+/* ── interrupt-free vblank sync (poll VDP status S#0 bit 7) ────────────── */
+__sfr __at 0x99 VDPSTATUS;
+static void vsync(void) {
+    (void)VDPSTATUS;
+    while (!(VDPSTATUS & 0x80)) {
+    }
+}
+
+/* fire-button trigger uses the BIOS GTTRIG wrapper (gttrig) from msx_hw.h:
+ * gttrig(0)=space/any, gttrig(1)/gttrig(2)=port-A/B triggers. */
+
+#define MAX_BULLETS 4
+#define MAX_ENEMIES 4
+
+/* ── tile font: SPACE, S C O R E, digits, plus a couple starfield tiles ── */
+#define T_SPACE 0
+#define T_S     1
+#define T_C     2
+#define T_O     3
+#define T_R     4
+#define T_E     5
+#define T_0     6   /* digits 0..9 are consecutive: T_0 + n */
+#define T_DEEP  16  /* solid deep-space band (dark blue)        */
+#define T_BAND  17  /* solid lighter space band (medium blue)   */
+#define T_STAR1 18  /* deep-space cell with a faint star        */
+#define T_STAR2 19  /* lighter-band cell with a bright star     */
+
+static const uint8_t font[20][8] = {
+    /* 0  SPACE */ {0,0,0,0,0,0,0,0},
+    /* 1  S */ {0x7C,0xC0,0xC0,0x78,0x0C,0x0C,0xF8,0x00},
+    /* 2  C */ {0x7C,0xC6,0xC0,0xC0,0xC0,0xC6,0x7C,0x00},
+    /* 3  O */ {0x7C,0xC6,0xC6,0xC6,0xC6,0xC6,0x7C,0x00},
+    /* 4  R */ {0xFC,0xC6,0xC6,0xFC,0xD8,0xCC,0xC6,0x00},
+    /* 5  E */ {0xFE,0xC0,0xC0,0xF8,0xC0,0xC0,0xFE,0x00},
+    /* 6  0 */ {0x7C,0xCE,0xDE,0xF6,0xE6,0xC6,0x7C,0x00},
+    /* 7  1 */ {0x18,0x38,0x18,0x18,0x18,0x18,0x7E,0x00},
+    /* 8  2 */ {0x7C,0xC6,0x06,0x1C,0x70,0xC0,0xFE,0x00},
+    /* 9  3 */ {0x7C,0xC6,0x06,0x3C,0x06,0xC6,0x7C,0x00},
+    /* 10 4 */ {0x1C,0x3C,0x6C,0xCC,0xFE,0x0C,0x0C,0x00},
+    /* 11 5 */ {0xFE,0xC0,0xFC,0x06,0x06,0xC6,0x7C,0x00},
+    /* 12 6 */ {0x3C,0x60,0xC0,0xFC,0xC6,0xC6,0x7C,0x00},
+    /* 13 7 */ {0xFE,0x06,0x0C,0x18,0x30,0x30,0x30,0x00},
+    /* 14 8 */ {0x7C,0xC6,0xC6,0x7C,0xC6,0xC6,0x7C,0x00},
+    /* 15 9 */ {0x7C,0xC6,0xC6,0x7E,0x06,0x0C,0x78,0x00},
+    /* 16 DEEP  (solid fill) */ {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF},
+    /* 17 BAND  (solid fill) */ {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF},
+    /* 18 STAR1 (deep + dot) */ {0xFF,0xFF,0xFF,0xEF,0xFF,0xFF,0xFF,0xFF},
+    /* 19 STAR2 (band + dot) */ {0xFF,0xEF,0xEF,0x83,0xEF,0xEF,0xFF,0xFF}
+};
+
+/* colour bytes per glyph: high nibble fg, low nibble bg.
+ * TMS9918 fixed palette: 1=black, 4=dark blue, 5=med blue, 14=grey, 15=white.
+ * The solid space tiles fill entirely with their fg colour. The star tiles
+ * use a white star (fg) over the band colour (bg). */
+#define COL_TEXT  0xF1   /* white text on black                       */
+#define COL_DEEP  0x44   /* solid dark-blue deep space                */
+#define COL_BAND  0x55   /* solid medium-blue band                    */
+#define COL_STAR1 0xF4   /* white star pixel over dark-blue field     */
+#define COL_STAR2 0xF5   /* white star over medium-blue band          */
+
+/* ── sprite patterns (8x8) ─────────────────────────────────────────────── */
+static const uint8_t spr_ship[8]   = {0x18,0x3C,0x7E,0x7E,0xFF,0xFF,0xDB,0x81};
+static const uint8_t spr_bullet[8] = {0x18,0x3C,0x3C,0x3C,0x3C,0x3C,0x18,0x00};
+static const uint8_t spr_enemy[8]  = {0x81,0x42,0x24,0x18,0x18,0x24,0x42,0x81};
+
+#define PAT_SHIP   0
+#define PAT_BULLET 1
+#define PAT_ENEMY  2
+
+/* TMS9918 fixed sprite palette: 15=white, 10=yellow, 9=red(ish) */
+#define COL_SHIP   15
+#define COL_BULLET 10
+#define COL_ENEMY  9
+
+typedef struct { uint8_t x, y, alive; } Obj;
+
+static Obj      player;
+static Obj      bullets[MAX_BULLETS];
+static Obj      enemies[MAX_ENEMIES];
+static uint16_t score;
+static uint8_t  spawn_timer;
+static uint16_t rng;
+static uint8_t  blip;
+
+static uint8_t next_rand(void) {
+    rng ^= (uint16_t)(rng << 7);
+    rng ^= (uint16_t)(rng >> 9);
+    rng ^= (uint16_t)(rng << 8);
+    return (uint8_t)(rng & 0xFF);
+}
+
+/* upload the glyph patterns into ALL THREE screen-2 pattern thirds */
+static void load_font(void) {
+    uint8_t third, i;
+    uint16_t patbase, colbase;
+    for (third = 0; third < 3; third++) {
+        patbase = (uint16_t)(VRAM_PATTERN + ((uint16_t)third << 11));
+        colbase = (uint16_t)(VRAM_COLOR   + ((uint16_t)third << 11));
+        for (i = 0; i < 20; i++) {
+            uint8_t col = COL_TEXT;
+            if (i == T_DEEP) col = COL_DEEP;
+            else if (i == T_BAND) col = COL_BAND;
+            else if (i == T_STAR1) col = COL_STAR1;
+            else if (i == T_STAR2) col = COL_STAR2;
+            msx_vram_write((uint16_t)(patbase + ((uint16_t)i << 3)), font[i], 8);
+            msx_fill_vram((uint16_t)(colbase + ((uint16_t)i << 3)), 8, col);
+        }
+    }
+}
+
+static void put_tile(uint8_t col, uint8_t row, uint8_t tile) {
+    msx_vram_write((uint16_t)(VRAM_NAME + (uint16_t)row * 32 + col), &tile, 1);
+}
+
+/* paint a banded starfield across the WHOLE 32x24 name table: alternating
+ * 3-row bands of deep/medium blue (so neither colour dominates) with a sparse
+ * scattering of white stars. Row 0 stays blank for the SCORE line. */
+static void draw_starfield(void) {
+    uint8_t row, col, band, tile, h;
+    msx_fill_vram(VRAM_NAME, 32, T_SPACE);   /* blank row 0 (HUD) */
+    for (row = 1; row < 24; row++) {
+        band = (uint8_t)(((row / 3) & 1));   /* alternate every 3 rows */
+        for (col = 0; col < 32; col++) {
+            h = (uint8_t)((row * 7 + col * 5) & 15);
+            if (h == 0) tile = band ? T_STAR2 : T_STAR1;  /* a star */
+            else tile = band ? T_BAND : T_DEEP;           /* solid band */
+            put_tile(col, row, tile);
+        }
+    }
+}
+
+static void draw_label(void) {
+    put_tile(1, 0, T_S); put_tile(2, 0, T_C); put_tile(3, 0, T_O);
+    put_tile(4, 0, T_R); put_tile(5, 0, T_E);
+}
+
+static void draw_score(void) {
+    uint16_t s = score;
+    put_tile(7, 0, (uint8_t)(T_0 + (s / 100) % 10));
+    put_tile(8, 0, (uint8_t)(T_0 + (s / 10) % 10));
+    put_tile(9, 0, (uint8_t)(T_0 + s % 10));
+}
+
+static uint8_t aabb(Obj *a, Obj *b) {
+    return a->x < b->x + 8 && a->x + 8 > b->x
+        && a->y < b->y + 8 && a->y + 8 > b->y;
+}
+
+static void fire(void) {
+    uint8_t i;
+    for (i = 0; i < MAX_BULLETS; i++) {
+        if (!bullets[i].alive) {
+            bullets[i].x = player.x;
+            bullets[i].y = (uint8_t)(player.y - 8);
+            bullets[i].alive = 1;
+            msx_psg_tone(0, 0x100, 12);
+            blip = 4;
+            return;
+        }
+    }
+}
+
+static void spawn(void) {
+    uint8_t i;
+    for (i = 0; i < MAX_ENEMIES; i++) {
+        if (!enemies[i].alive) {
+            enemies[i].x = (uint8_t)(8 + (next_rand() % 232));
+            enemies[i].y = 16;
+            enemies[i].alive = 1;
+            return;
+        }
+    }
+}
+
+void main(void) {
+    uint8_t i, j, dir, trig, prev_trig;
+
+    msx_set_screen2();
+    msx_clear_sprites();
+    load_font();
+    draw_starfield();
+    draw_label();
+
+    msx_vram_write((uint16_t)(VRAM_SPRPAT + PAT_SHIP   * 8), spr_ship,   8);
+    msx_vram_write((uint16_t)(VRAM_SPRPAT + PAT_BULLET * 8), spr_bullet, 8);
+    msx_vram_write((uint16_t)(VRAM_SPRPAT + PAT_ENEMY  * 8), spr_enemy,  8);
+
+    player.x = 120; player.y = 160; player.alive = 1;
+    for (i = 0; i < MAX_BULLETS; i++) bullets[i].alive = 0;
+    for (i = 0; i < MAX_ENEMIES; i++) enemies[i].alive = 0;
+    score = 0;
+    spawn_timer = 0;
+    rng = 0xACE1;
+    blip = 0;
+    prev_trig = 0;
+    draw_score();
+
+    for (;;) {
+        vsync();
+
+        dir = msx_read_joystick(1);
+        if (dir == STICK_CENTER) dir = msx_read_joystick(0);
+        trig = (uint8_t)(gttrig(1) || gttrig(2));
+
+        if ((dir == STICK_LEFT || dir == STICK_UL || dir == STICK_DL)
+            && player.x > 4) player.x = (uint8_t)(player.x - 2);
+        if ((dir == STICK_RIGHT || dir == STICK_UR || dir == STICK_DR)
+            && player.x < 248) player.x = (uint8_t)(player.x + 2);
+        if ((dir == STICK_UP || dir == STICK_UL || dir == STICK_UR)
+            && player.y > 16) player.y = (uint8_t)(player.y - 2);
+        if ((dir == STICK_DOWN || dir == STICK_DL || dir == STICK_DR)
+            && player.y < 168) player.y = (uint8_t)(player.y + 2);
+
+        if (trig && !prev_trig) fire();
+        prev_trig = trig;
+
+        /* advance bullets */
+        for (i = 0; i < MAX_BULLETS; i++) {
+            if (!bullets[i].alive) continue;
+            if (bullets[i].y < 18) { bullets[i].alive = 0; continue; }
+            bullets[i].y = (uint8_t)(bullets[i].y - 4);
+        }
+        /* advance enemies */
+        for (i = 0; i < MAX_ENEMIES; i++) {
+            if (!enemies[i].alive) continue;
+            enemies[i].y = (uint8_t)(enemies[i].y + 1);
+            if (enemies[i].y >= 184) enemies[i].alive = 0;
+        }
+        spawn_timer = (uint8_t)(spawn_timer + 1);
+        if (spawn_timer >= 28) { spawn_timer = 0; spawn(); }
+
+        /* bullet vs enemy */
+        for (i = 0; i < MAX_BULLETS; i++) {
+            if (!bullets[i].alive) continue;
+            for (j = 0; j < MAX_ENEMIES; j++) {
+                if (!enemies[j].alive) continue;
+                if (aabb(&bullets[i], &enemies[j])) {
+                    bullets[i].alive = 0;
+                    enemies[j].alive = 0;
+                    if (score < 999) { score++; draw_score(); }
+                    msx_psg_tone(1, 0x400, 14);
+                    blip = 6;
+                    break;
+                }
+            }
+        }
+
+        if (blip) { blip--; if (!blip) { msx_psg_off(0); msx_psg_off(1); } }
+
+        /* push sprites */
+        msx_set_sprite(0, player.x, player.y, PAT_SHIP, COL_SHIP);
+        for (i = 0; i < MAX_BULLETS; i++)
+            msx_set_sprite((uint8_t)(1 + i), bullets[i].x,
+                           bullets[i].alive ? bullets[i].y : SPRITE_END_Y,
+                           PAT_BULLET, COL_BULLET);
+        for (i = 0; i < MAX_ENEMIES; i++)
+            msx_set_sprite((uint8_t)(5 + i), enemies[i].x,
+                           enemies[i].alive ? enemies[i].y : SPRITE_END_Y,
+                           PAT_ENEMY, COL_ENEMY);
+    }
+}

package/examples/msx/sports/main.c

@@ -0,0 +1,182 @@
+/* ── sports/main.c — MSX two-player Pong scaffold (screen 2) ─────────
+ *
+ * Mirrors the SMS/GB/etc Pong scaffolds, translated to the MSX VDP via the
+ * romdev helper lib (msx_hw.h + msx_vdp.c).
+ *
+ * The court (green field + white top/bottom + sidelines + dashed centre
+ * net) fills the whole 32x24 screen-2 name table. Two paddles (each three
+ * stacked 8x8 sprites) and a ball are sprites.
+ *
+ * Controls:
+ *   Player 1 — joystick PORT 1 UP/DOWN moves the left paddle.
+ *   Player 2 — joystick PORT 2 UP/DOWN moves the right paddle; when no
+ *     second pad is present (stick 2 reads centre) the right paddle falls
+ *     back to chase-the-ball AI, so the game is playable solo. Plug a
+ *     second pad in mid-session and player 2 just starts working.
+ *
+ * Cartridge rule: INIT must never return — main() ends in for(;;).
+ */
+#include "msx_hw.h"
+
+/* ── interrupt-free vblank sync (poll VDP status S#0 bit 7) ────────────── */
+__sfr __at 0x99 VDPSTATUS;
+static void vsync(void) {
+    (void)VDPSTATUS;
+    while (!(VDPSTATUS & 0x80)) {
+    }
+}
+
+#define COURT_TOP   16
+#define COURT_BOT   184
+#define PADDLE_H    24
+#define BALL_SIZE   8
+#define PADDLE_X1   16
+#define PADDLE_X2   232
+
+/* tile patterns (8x8) for the court */
+#define T_FIELD 0
+#define T_LINE  1
+#define T_NET   2
+
+static const uint8_t TILE_FIELD[8] = {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF};
+static const uint8_t TILE_LINE[8]  = {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF};
+static const uint8_t TILE_NET[8]   = {0x18,0x18,0x00,0x00,0x18,0x18,0x00,0x00};
+
+/* colour bytes (hi fg, lo bg). 3=green(dark), 12=green(light), 15=white */
+#define COL_FIELD 0x21   /* dark green field on black             */
+#define COL_LINE  0xF1   /* white line on black                   */
+#define COL_NET   0xF2   /* white net dashes on dark-green field  */
+
+/* paddle/ball sprite pattern (8x8 solid block) */
+static const uint8_t SPR_BLOCK[8] = {0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF};
+#define COL_SPR 15   /* white */
+
+static int16_t p1y, p2y, bx, by;
+static int8_t  bdx, bdy;
+static uint8_t score_p1, score_p2;
+static uint8_t serve_timer;
+static uint8_t blip;
+
+static void load_tiles(void) {
+    uint8_t third;
+    uint16_t pat, col;
+    for (third = 0; third < 3; third++) {
+        pat = (uint16_t)(VRAM_PATTERN + ((uint16_t)third << 11));
+        col = (uint16_t)(VRAM_COLOR   + ((uint16_t)third << 11));
+        msx_vram_write((uint16_t)(pat + T_FIELD * 8), TILE_FIELD, 8);
+        msx_vram_write((uint16_t)(pat + T_LINE  * 8), TILE_LINE,  8);
+        msx_vram_write((uint16_t)(pat + T_NET   * 8), TILE_NET,   8);
+        msx_fill_vram((uint16_t)(col + T_FIELD * 8), 8, COL_FIELD);
+        msx_fill_vram((uint16_t)(col + T_LINE  * 8), 8, COL_LINE);
+        msx_fill_vram((uint16_t)(col + T_NET   * 8), 8, COL_NET);
+    }
+}
+
+static void set_cell(uint8_t row, uint8_t col, uint8_t tile) {
+    msx_vram_write((uint16_t)(VRAM_NAME + (uint16_t)row * 32 + col), &tile, 1);
+}
+
+static void draw_court(void) {
+    uint8_t row, col, t;
+    for (row = 0; row < 24; row++) {
+        for (col = 0; col < 32; col++) {
+            t = T_FIELD;
+            if (row <= 1 || row >= 22) t = T_LINE;
+            else if (col == 1 || col == 30) t = T_LINE;
+            else if (col == 16) t = T_NET;
+            set_cell(row, col, t);
+        }
+    }
+}
+
+static void serve_ball(uint8_t to_left) {
+    bx = 124;
+    by = 90;
+    bdx = to_left ? -2 : 2;
+    bdy = ((score_p1 + score_p2) & 1) ? -1 : 1;
+    serve_timer = 30;
+}
+
+static void reset_match(void) {
+    p1y = 84; p2y = 84;
+    score_p1 = 0; score_p2 = 0;
+    serve_ball(0);
+}
+
+void main(void) {
+    uint8_t i, slot, p1, p2;
+    int16_t target;
+
+    msx_set_screen2();
+    msx_clear_sprites();
+    load_tiles();
+    draw_court();
+    msx_vram_write((uint16_t)(VRAM_SPRPAT + 0), SPR_BLOCK, 8);
+
+    blip = 0;
+    reset_match();
+
+    for (;;) {
+        vsync();
+
+        /* push sprites: left paddle (3 cells), right paddle (3), ball */
+        slot = 0;
+        for (i = 0; i < PADDLE_H / 8; i++)
+            msx_set_sprite(slot++, PADDLE_X1, (uint8_t)(p1y + i * 8), 0, COL_SPR);
+        for (i = 0; i < PADDLE_H / 8; i++)
+            msx_set_sprite(slot++, PADDLE_X2, (uint8_t)(p2y + i * 8), 0, COL_SPR);
+        msx_set_sprite(slot++, (uint8_t)bx, (uint8_t)by, 0, COL_SPR);
+
+        p1 = msx_read_joystick(1);
+        p2 = msx_read_joystick(2);
+
+        if ((p1 == STICK_UP || p1 == STICK_UL || p1 == STICK_UR)
+            && p1y > COURT_TOP) p1y -= 3;
+        if ((p1 == STICK_DOWN || p1 == STICK_DL || p1 == STICK_DR)
+            && p1y < COURT_BOT - PADDLE_H) p1y += 3;
+
+        if (p2 != STICK_CENTER) {
+            if ((p2 == STICK_UP || p2 == STICK_UL || p2 == STICK_UR)
+                && p2y > COURT_TOP) p2y -= 3;
+            if ((p2 == STICK_DOWN || p2 == STICK_DL || p2 == STICK_DR)
+                && p2y < COURT_BOT - PADDLE_H) p2y += 3;
+        } else {
+            target = (int16_t)(by - PADDLE_H / 2);
+            if (p2y < target && p2y < COURT_BOT - PADDLE_H) p2y += 2;
+            else if (p2y > target && p2y > COURT_TOP) p2y -= 2;
+        }
+
+        if (serve_timer > 0) {
+            serve_timer--;
+        } else {
+            bx = (int16_t)(bx + bdx);
+            by = (int16_t)(by + bdy);
+            if (by < COURT_TOP) { by = COURT_TOP; bdy = (int8_t)(-bdy); msx_psg_tone(1, 0x300, 8); blip = 3; }
+            if (by + BALL_SIZE > COURT_BOT) { by = (int16_t)(COURT_BOT - BALL_SIZE); bdy = (int8_t)(-bdy); msx_psg_tone(1, 0x300, 8); blip = 3; }
+
+            if (bdx < 0
+                && bx <= PADDLE_X1 + 8
+                && bx + BALL_SIZE >= PADDLE_X1
+                && by + BALL_SIZE > p1y
+                && by < p1y + PADDLE_H) {
+                bdx = (int8_t)(-bdx);
+                bx = PADDLE_X1 + 8;
+                msx_psg_tone(0, 0x200, 10); blip = 4;
+            }
+            if (bdx > 0
+                && bx + BALL_SIZE >= PADDLE_X2
+                && bx <= PADDLE_X2 + 8
+                && by + BALL_SIZE > p2y
+                && by < p2y + PADDLE_H) {
+                bdx = (int8_t)(-bdx);
+                bx = (int16_t)(PADDLE_X2 - BALL_SIZE);
+                msx_psg_tone(0, 0x200, 10); blip = 4;
+            }
+
+            if (bx < 4)   { if (score_p2 < 9) score_p2++; msx_psg_tone(0, 0x500, 14); blip = 8; serve_ball(0); }
+            if (bx > 252) { if (score_p1 < 9) score_p1++; msx_psg_tone(0, 0x180, 14); blip = 8; serve_ball(1); }
+        }
+
+        if (blip) { blip--; if (!blip) { msx_psg_off(0); msx_psg_off(1); } }
+    }
+}

package/examples/nes/templates/default.c

@@ -1,44 +1,92 @@
 /* ── default.c — minimal NES starter ────────────────────────────
  *
- * Cycles the backdrop color (palette entry $3F00) through 4 shades.
- * Smallest possible "ROM that does something visible" — use this as
- * the starting point when you're not yet sure what you want to build.
+ * A "hello, it works!" screen: a tiled background band + a bouncing
+ * sprite, so the very first build shows recognizable content (not a
+ * flat color). Smallest starting point when you're not yet sure what
+ * you want to build — edit from here.
  *
  * For something more game-shaped:
  *   - hello_sprite — sprite + d-pad movement
  *   - tile_engine  — 32×30 nametable + rooms + door transitions
+ *   - scaffold({op:'game', genre:'shmup'|'platformer'|...}) — full genres
  *
- * Both available via createProject({platform:"nes", template:"..."}).
+ * NES uses CHR-RAM here, so we upload our tile graphics at boot before
+ * turning rendering on (an empty CHR-RAM = a blank screen — the #1 NES
+ * "why is it black" footgun; see TROUBLESHOOTING.md).
  */
 
 #include "nes_runtime.h"
 
-/* 4 VISIBLE hues — never 0x0F (black), so a screenshot on ANY phase of the
- * cycle shows a non-black backdrop (NES-2: the old cycle started on + passed
- * through black, so a fresh agent's screenshot could land on a "blank" frame). */
-static const uint8_t bg_colors[4] = { 0x21, 0x01, 0x11, 0x31 };
+/* Two 8×8 tiles in 2bpp NES format (plane0 = low bit, plane1 = high bit;
+ * 8 bytes each). Tile 1 = a solid filled block (color 1). Tile 2 = a simple
+ * face/box so the sprite reads as an object. */
+static const uint8_t tiles[32] = {
+  /* tile 1 — solid block: plane0 all-on, plane1 all-off → every pixel color 1 */
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  /* tile 2 — sprite: a filled diamond/box (color 1 outline + fill) */
+  0x18,0x3C,0x7E,0xFF,0xFF,0x7E,0x3C,0x18,
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+};
+
+/* 32-byte palette: BG palette 0 gives the block a bright color on a blue
+ * backdrop; sprite palette 0 colour 1 = yellow so the sprite pops. */
+static const uint8_t palette[32] = {
+  0x01, 0x30, 0x21, 0x0F,   /* BG0: backdrop blue, block white, ... */
+  0x01, 0x30, 0x21, 0x0F,
+  0x01, 0x30, 0x21, 0x0F,
+  0x01, 0x30, 0x21, 0x0F,
+  0x0F, 0x28, 0x16, 0x30,   /* SPR0: colour1 yellow */
+  0x0F, 0x28, 0x16, 0x30,
+  0x0F, 0x28, 0x16, 0x30,
+  0x0F, 0x28, 0x16, 0x30,
+};
 
 void main(void) {
-  uint8_t palette[32];
-  uint8_t i;
-  uint8_t shade = 0;
+  uint8_t x, y;
+  uint8_t sx = 120, sy = 96;     /* sprite position */
+  int8_t dx = 1, dy = 1;         /* sprite velocity */
   uint8_t frame = 0;
 
-  for (i = 0; i < 32; i++) palette[i] = bg_colors[0];
-
   ppu_off();
+  /* The runtime's default PPUCTRL puts SPRITES at pattern table $0000 and the
+   * BACKGROUND at $1000 — two separate 4KB tables. So upload the block tile to
+   * the BG table ($1000, slot 1 → $1010) AND the sprite tile to the sprite
+   * table ($0000, slot 2 → $0020). (Uploading only to $0000 = invisible BG, the
+   * classic "my tiles are in the wrong pattern table" NES gotcha.) */
+  chr_ram_upload(0x1010, tiles,      16);  /* BG  block  → BG tile index 1  */
+  chr_ram_upload(0x0020, tiles + 16, 16);  /* SPR object → sprite tile index 2 */
   palette_load(palette);
   oam_clear();
+
+  /* Populate the nametable DIRECTLY while rendering is off. We use
+   * vram_unsafe_set (a raw PPU write) here on purpose: the friendly tile_set()
+   * goes through the NMI-flushed queue (24 entries), which would deadlock if you
+   * push hundreds of tiles before turning the PPU on. The "write VRAM directly
+   * while off, then turn on" idiom is the standard NES way to lay out a screen.
+   * Tile index 1 = the solid block. */
+  for (x = 0; x < 32; x++) {
+    vram_unsafe_set((uint16_t)(0x2000 + 4 * 32 + x), 1);    /* top band  (row 4)  */
+    vram_unsafe_set((uint16_t)(0x2000 + 25 * 32 + x), 1);   /* bottom band (row 25) */
+  }
+  for (y = 10; y < 18; y++) {
+    for (x = 8; x < 24; x++)
+      vram_unsafe_set((uint16_t)(0x2000 + (uint16_t)y * 32 + x), 1);  /* center box */
+  }
+
   ppu_on_all();
 
   for (;;) {
+    /* stage the sprite BEFORE waiting (NMI DMAs shadow_oam at vblank). */
+    oam_clear();
+    oam_spr(sx, sy, 2, 0);         /* tile 2, sprite palette 0 */
     ppu_wait_nmi();
+
     ++frame;
-    if ((frame & 0x1F) == 0) {       /* every 32 frames */
-      shade = (uint8_t)((shade + 1) & 0x03);
-      /* Only the backdrop entry ($3F00) needs updating for a flash.
-       * vram_set queues the write — NMI commits it next vblank. */
-      vram_set(0x3F00, bg_colors[shade]);
-    }
+    /* bounce the sprite around the visible area */
+    sx = (uint8_t)(sx + dx);
+    sy = (uint8_t)(sy + dy);
+    if (sx < 8 || sx > 240) dx = (int8_t)-dx;
+    if (sy < 16 || sy > 208) dy = (int8_t)-dy;
   }
 }

package/examples/nes/templates/hello_sprite.c

@@ -32,6 +32,21 @@ static const uint8_t tile_data[16] = {
   0,    0,    0,    0,    0,    0,    0,    0,
 };
 
+/* Two BG tiles so the backdrop isn't a single flat colour (a uniform
+ * screen reads >=92% one colour and fails the blank-screen check):
+ *   tile 1 — solid colour 1
+ *   tile 2 — solid colour 2
+ * Checkerboarded across the nametable below. BG fetches from $1000-$1FFF
+ * under the default PPUCTRL, so these upload to the BG pattern table. */
+static const uint8_t bg_tiles[2 * 16] = {
+  /* tile 1: solid colour 1 */
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  /* tile 2: solid colour 2 */
+  0x00,0x00,0x00,0x00,0x00,0x00,0x00,0x00,
+  0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,0xFF,
+};
+
 /* 32-byte palette: 4 BG palettes + 4 sprite palettes.
  * BG  index 0 ($3F00) is the universal backdrop.
  * SPR index 0 ($3F10) is transparent — always; the value is written
@@ -49,6 +64,21 @@ static const uint8_t palette[32] = {
   0x0F, 0x2A, 0x1A, 0x0A,
 };
 
+/* Fill nametable 0 ($2000) with a checkerboard of BG tiles 1 and 2 so the
+ * screen behind the sprite is visibly NOT blank. Attribute table stays at
+ * palette 0. Caller must have the PPU off. */
+static void fill_bg(void) {
+  uint16_t addr;
+  uint8_t y, x;
+  for (y = 0; y < 30; y++) {
+    addr = (uint16_t)(0x2000 + (uint16_t)y * 32);
+    for (x = 0; x < 32; x++) {
+      vram_unsafe_set(addr, (uint8_t)(((x ^ y) & 1) + 1));
+      ++addr;
+    }
+  }
+}
+
 void main(void) {
   uint8_t px = 124;       /* mid-screen X */
   uint8_t py = 110;       /* mid-screen Y */
@@ -64,6 +94,11 @@ void main(void) {
    * at $0000-$0FFF since the default PPUCTRL has sprite_pattern=0. */
   chr_ram_upload(0x0010, tile_data, 16);
 
+  /* ── 2b. Upload BG tiles to the BG pattern table at $1000 and paint
+   * a checkerboard backdrop so the sprite isn't alone on a blank field. */
+  chr_ram_upload(0x1000, bg_tiles, sizeof(bg_tiles));
+  fill_bg();
+
   /* ── 3. Load palette ─────────────────────────────────────────── */
   palette_load(palette);