romdevtools 0.13.0

package/examples/pce/sprite_move/main.c

@@ -0,0 +1,155 @@
+/*
+ * PC Engine "sprite_move" — a joypad-controlled 16x16 sprite over a tiled BG.
+ *
+ * Press the d-pad to slide a yellow-faced sprite around a green/dark checkerboard
+ * background. This is the canonical PCE "read pad + move a sprite over a tilemap"
+ * starter: it exercises the whole helper library end to end —
+ *
+ *   vce_set_color()           BG + sprite palette entries (9-bit GRB)
+ *   load_tiles()/vram_write() tile patterns + sprite pattern into VRAM
+ *   (fill_bat)                a tiled background map streamed to the BAT
+ *   set_sprite()+satb_dma()   a 16x16 sprite via the shadow SATB + R19 DMA
+ *   bg_enable()/spr_enable()  master display-enable + VBlank IRQ (waitvsync)
+ *   pce_joy_init/pce_joy_read d-pad input
+ *
+ * BUILD: link main.c + pce_video.c + pce_input.c + pce_sound.c together, with
+ * pce_hw.h in includes. (PCE cc65 target supplies crt0 + pce.lib automatically.)
+ *
+ * cc65 is C89 — declare locals at the top of a block. A cart INIT must never
+ * return, so main() ends in for(;;){}.
+ *
+ * EMPTY-BSS TRAP: linking pce_video.c pulls in _pce_keep[4], so .bss is never
+ * empty (no ld65 range-error / black screen). We touch _pce_keep[0] for clarity.
+ */
+#include <pce.h>
+#include "pce_hw.h"
+
+/* ------------------------------------------------------------------ VRAM map */
+#define TILE_A_VRAM   0x1000   /* 8x8 BG tile A (green block)   */
+#define TILE_B_VRAM   0x1010   /* 8x8 BG tile B (dark block)    */
+#define SPR_VRAM      0x1800   /* 16x16 sprite pattern          */
+#define BAT_VRAM      0x0000   /* background attribute table    */
+
+/* The BAT entry packs: bits 0..11 = (tileVramWordAddr >> 4), bits 12..15 = the
+ * 16-color BG sub-palette. We use sub-palette 0 for both tiles. */
+#define BAT_ENTRY(vram, pal)  ((u16)(((u16)(pal) << 12) | ((u16)(vram) >> 4)))
+
+/* Tile pattern buffers. PCE tiles are 4bpp, 8x8 = 16 words (4 bitplanes x 8
+ * rows, interleaved as plane0/1 first 8 words, plane2/3 next 8 words). */
+static u16 tile_a[16];   /* color index 1 -> green */
+static u16 tile_b[16];   /* color index 2 -> dark teal */
+
+/* 16x16 sprite = 64 words. A little face: outline in color 1, eyes/mouth in 2. */
+static u16 sprite_cell[64];
+
+/* Player position (top-left of the 16x16 sprite, in pixels). */
+static u16 px, py;
+static u8  pad;
+
+/* Build an 8x8 tile that is a SOLID fill of `ci` (color index 1..15). For a
+ * 4bpp tile, color index `ci` means: for each of the 4 bitplanes p, set the
+ * row byte to 0xFF if bit p of ci is set. plane0/1 occupy words 0..7,
+ * plane2/3 words 8..15; each word's low byte = even plane, high byte = odd. */
+static void make_solid_tile(u16 *t, u8 ci) {
+    u8 r;
+    u8 p0 = (ci & 1) ? 0xFF : 0x00;
+    u8 p1 = (ci & 2) ? 0xFF : 0x00;
+    u8 p2 = (ci & 4) ? 0xFF : 0x00;
+    u8 p3 = (ci & 8) ? 0xFF : 0x00;
+    for (r = 0; r < 8; ++r) {
+        t[r]     = (u16)(p0 | (p1 << 8));   /* planes 0 (lo) + 1 (hi) */
+        t[r + 8] = (u16)(p2 | (p3 << 8));   /* planes 2 (lo) + 3 (hi) */
+    }
+}
+
+/* Build the 16x16 sprite face. PCE 16x16 sprite = 64 words: 4 bitplanes, each
+ * plane is 16 rows of 16-bit masks, stored plane0[16], plane1[16], plane2[16],
+ * plane3[16]. We only need 2 colors:
+ *   color 1 (plane0 bit set)  -> face fill
+ *   color 2 (plane1 bit set)  -> eyes + mouth
+ * `face[r]` is the 16-bit row mask for the body; `feat[r]` for the features. */
+static void make_sprite(void) {
+    static const u16 face[16] = {
+        0x0000, 0x07E0, 0x1FF8, 0x3FFC, 0x7FFE, 0x7FFE, 0xFFFF, 0xFFFF,
+        0xFFFF, 0xFFFF, 0x7FFE, 0x7FFE, 0x3FFC, 0x1FF8, 0x07E0, 0x0000
+    };
+    /* eyes on rows 5-6, mouth on rows 10-11 */
+    static const u16 feat[16] = {
+        0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x1818, 0x1818, 0x0000,
+        0x0000, 0x0000, 0x3C3C, 0x3C3C, 0x0000, 0x0000, 0x0000, 0x0000
+    };
+    u8 r;
+    for (r = 0; r < 64; ++r) sprite_cell[r] = 0;
+    for (r = 0; r < 16; ++r) {
+        /* plane0 = face body MINUS the feature pixels (so they read color 2) */
+        sprite_cell[r]      = (u16)(face[r] & ~feat[r]);
+        /* plane1 = the feature pixels -> color index 2 */
+        sprite_cell[r + 16] = feat[r];
+        /* planes 2,3 stay zero */
+    }
+}
+
+/* Draw a 32x32-cell checkerboard of TILE_A / TILE_B across the BAT. The default
+ * PCE virtual screen is 32x32 cells (256x256 px), which covers the display. */
+static void fill_bat(void) {
+    u16 ea = BAT_ENTRY(TILE_A_VRAM, 0);
+    u16 eb = BAT_ENTRY(TILE_B_VRAM, 0);
+    u16 r, col, e;
+    for (r = 0; r < 32; ++r) {
+        vram_set_write_addr((u16)(BAT_VRAM + r * 32));
+        for (col = 0; col < 32; ++col) {
+            e = ea;     /* solid background so the sprite stands out */
+            VDC_DATA_LO = (u8)(e & 0xFF);
+            VDC_DATA_HI = (u8)(e >> 8);
+        }
+    }
+}
+
+void main(void) {
+    _pce_keep[0] = 0;
+
+    px = 120; py = 100;
+
+    /* --- palettes ---------------------------------------------------------- */
+    /* BG sub-palette 0: index 0 = backdrop, 1 = green, 2 = dark teal. */
+    vce_set_color(0, PCE_RGB(0, 0, 1));   /* backdrop: near-black blue */
+    vce_set_color(1, PCE_RGB(1, 6, 1));   /* BG color 1: green         */
+    vce_set_color(2, PCE_RGB(0, 2, 2));   /* BG color 2: dark teal     */
+    /* Sprite sub-palette 0 lives at VCE 256..271. */
+    vce_set_color(256, PCE_RGB(0, 0, 0)); /* sprite transparent        */
+    vce_set_color(257, PCE_RGB(7, 7, 7)); /* sprite color 1: white     */
+    vce_set_color(258, PCE_RGB(7, 1, 0)); /* sprite color 2: red       */
+
+    /* --- patterns ---------------------------------------------------------- */
+    make_solid_tile(tile_a, 1);
+    make_solid_tile(tile_b, 2);
+    make_sprite();
+
+    load_tiles(TILE_A_VRAM, tile_a, 16);
+    load_tiles(TILE_B_VRAM, tile_b, 16);
+    load_tiles(SPR_VRAM,    sprite_cell, 64);
+
+    fill_bat();
+
+    /* --- first sprite frame ------------------------------------------------ */
+    /* set_sprite pattern arg = the 16x16 cell index; the VDC pattern address is
+     * (cell << 1) words. SPR_VRAM word addr 0x1800 -> cell 0x1800 >> 6 = 0x60. */
+    set_sprite(0, px, py, SPR_VRAM >> 6, 0);
+    satb_dma();
+
+    /* --- enable display + input -------------------------------------------- */
+    bg_enable();
+    spr_enable();
+    pce_joy_init();
+
+    for (;;) {
+        waitvsync();
+        pad = pce_joy_read();
+        if ((pad & PCE_JOY_LEFT)  && px > 1)   px -= 2;
+        if ((pad & PCE_JOY_RIGHT) && px < 240) px += 2;
+        if ((pad & PCE_JOY_UP)    && py > 1)   py -= 2;
+        if ((pad & PCE_JOY_DOWN)  && py < 208) py += 2;
+        set_sprite(0, px, py, SPR_VRAM >> 6, 0);
+        satb_dma();
+    }
+}

package/examples/porting-across-platforms/README.md

@@ -0,0 +1,59 @@
+# Porting a small arcade game across platforms
+
+When you build the *same* game (a shmup, a fixed-shooter, a single-screen
+arcade game) on many retro systems, the hard part is **not** "write C" or "write
+asm." It's **choosing the right rendering primitive for each machine.** Pick
+wrong and you get output that's technically correct but looks bad — SNES sprites
+that read as dots, an Atari 2600 that looks like a barcode, a blank Lynx screen.
+This guide is the per-platform cheat-sheet so you reach for the right primitive
+on the first try.
+
+## The matrix
+
+For a Space-Invaders-shaped game (player at the bottom, a grid of enemies,
+shields/HUD, shots):
+
+| Platform | Enemies / player / shots | Shields & HUD | The thing that bites you |
+| --- | --- | --- | --- |
+| **GBA** | hardware OBJ sprites (or bitmap mode) | OBJ or BG | Easiest target — lots of headroom, simple output looks good. ⚠ Set up IRQs (`irq_init`+`irq_add(II_VBLANK)`) before `VBlankIntrWait()` or the BIOS halts forever. |
+| **Genesis** | VDP sprites + tiles | sprites or BG plane | Strong fit. ⚠ Step 60+ frames after boot before judging output — the VDP init takes a moment. |
+| **SMS** | VDP sprites + BG tiles | BG tilemap | ⚠ 8 sprites per scanline. Put score/status on the BG tilemap, not sprites. |
+| **Game Gear** | VDP sprites + BG | BG tiles | Same as SMS **plus** the visible screen is the center 160×144 of a 256×192 hardware space. Keep sprites inside the visible box (the scaffold ships `VIS_*` constants). |
+| **NES** | OAM sprites + CHR | BG nametable tiles | ⚠ 8 sprites per scanline → ≤5–6 enemies per row. ⚠ **Stage OAM (oam_clear/oam_spr) BEFORE `ppu_wait_nmi`** — the NMI DMAs shadow OAM at vblank start. ⚠ ~512 B of BSS on chr-ram (check `ramUsage` in the build result). |
+| **SNES** | OBJ sprites — use **chunky metasprites** (16×16 / 24×16), not lone 8×8 | OBJ or BG | The "looks like dots" trap: naive 8×8 OBJs are technically valid but tiny. Build a real CHR tileset, set OBJ size + the right palette line + CHR base. ⚠ Call `sfx_init()` AFTER `setScreenOn()` (a stalled SPC upload before screen-on = black screen). |
+| **GB / GBC** | OAM sprites | OAM + BG | ⚠ Copy tiles into VRAM with `memcpy_vram()`, never a raw `for(i){dst[i]=src[i]}` loop (SDCC miscompiles it → CPU crash). ⚠ uint16_t for loop bounds >255. On GBC, stage+DMA the first OAM frame before enabling the LCD. |
+| **C64** | VIC-II hardware sprites (cannon/shots) + character cells (invaders/shields) | character cells | It's a **computer/`.prg`**, not a ROM console. The character grid is great for the invader formation; hardware sprites for the few moving things. |
+| **Atari Lynx** | **full-redraw with `tgi_bar` rectangles** (Suzy blitter) | tgi_bar | ⚠ The loop MUST be: `while(tgi_busy()){}` → full-screen `tgi_bar` clear → draw → `tgi_updatedisplay()`. Skipping the busy-wait or using `tgi_clear()` = blank screen. Full redraw every frame is fine for a small game. |
+| **Atari 7800** | **MARIA display-list entries** (a "sprite" is a DL header) | DL entries / coarse | ⚠ No sprite table or tilemap. Build the DLL once at init; per frame, PATCH the existing DL entries in place (X / graphics ptr / palette). A full per-frame DLL rebuild = tearing/corruption. ≤~32 objects per scanline. |
+| **Atari 2600** | **TIA players + missiles, beam-raced** | reused player / coarse playfield | ⚠ The hardest. No framebuffer — everything is per-scanline register writes. P0 = ship (double-width), P1 + `NUSIZ1` hardware copies = invader row, P1 reused in a lower scanline region = shields, M0 = shot. Don't use playfield bits for aliens — it looks like a barcode. 128 B RAM. |
+
+## The one rule behind all of it
+
+**Match the primitive to the machine's native model, not to your mental
+model of "sprites."** Three machines in this list don't have a conventional
+sprite table at all:
+
+- **Lynx** is a blitter — you draw rectangles into a framebuffer every frame.
+- **7800** is a display-list processor — a "sprite" is a list entry you patch.
+- **2600** is a beam-raced register machine — you change TIA registers per
+  scanline; objects are reused vertically.
+
+If you try to force a tile/OAM mental model onto those three, you get blank or
+broken output. The other nine are sprite+tile machines where the main variables
+are the sprite-per-scanline limit and where text/HUD should live (BG, not
+sprites, on the constrained ones).
+
+## Recommended workflow
+
+1. **Prototype on GBA or Genesis first.** They have the most headroom, so you
+   nail the *gameplay* (movement, collision, waves, scoring) where the hardware
+   won't fight you.
+2. **Then port downward**, swapping only the rendering layer per the matrix.
+   The game logic is the same C; the `stage_sprites()` / draw routine is what
+   changes per platform.
+3. **Read the platform's `MENTAL_MODEL.md` + `TROUBLESHOOTING.md`** (via
+   `platform({op:'doc'})`) before writing its render layer — they lead with that
+   platform's specific footgun.
+4. **Verify visually, not just by exit code.** `build({output:'run'})` returns a screenshot;
+   `sprites({op:'inspect'})` / `background({view:'renderState'})` / `memory({op:'read'})` turn "blank screen"
+   into a concrete diagnosis. "It compiled" means nothing until you see a frame.

package/examples/sms/main.c

@@ -0,0 +1,129 @@
+/* SMS hello-world. Writes a yellow 'H' tile to VRAM, places it in the
+ * name table, enables display. Pressing P1-B1 scrolls the BG by one
+ * pixel per frame.
+ *
+ * Single-file example — pulls the SMS hardware port declarations
+ * directly. For a more realistic multi-file project, see
+ * src/platforms/sms/lib/c/ (vdp_init.c, load_tiles.c, etc.) — those
+ * snippets are bundled as part of the starter library:
+ *
+ *   getStarterSnippet({platform:"sms", name:"vdp_init", language:"c"})
+ */
+#include <stdint.h>
+
+/* ─── SMS hardware ports ──────────────────────────────────────────── */
+__sfr __at 0xBE PORT_VDP_DATA;
+__sfr __at 0xBF PORT_VDP_CTRL;
+__sfr __at 0xDC PORT_JOY_A;
+
+#define VDP_VRAM_WRITE 0x40
+#define VDP_REG_WRITE  0x80
+#define VDP_CRAM_WRITE 0xC0
+#define JOY_B1         0x10
+
+/* ─── VDP helpers ─────────────────────────────────────────────────── */
+static void vdp_write_reg(uint8_t reg, uint8_t value) {
+  PORT_VDP_CTRL = value;
+  PORT_VDP_CTRL = VDP_REG_WRITE | reg;
+}
+
+static void vdp_set_addr(uint16_t addr, uint8_t prefix) {
+  PORT_VDP_CTRL = (uint8_t)(addr & 0xFF);
+  PORT_VDP_CTRL = (uint8_t)((addr >> 8) & 0x3F) | prefix;
+}
+
+static void vdp_init(void) {
+  vdp_write_reg(0,  0x36);
+  vdp_write_reg(1,  0x80);  /* display OFF for now */
+  vdp_write_reg(2,  0xFF);  /* name table at $3800 */
+  vdp_write_reg(3,  0xFF);
+  vdp_write_reg(4,  0xFF);  /* BG tile data at $0000 */
+  vdp_write_reg(5,  0xFF);  /* sprite attr table at $3F00 */
+  vdp_write_reg(6,  0xFB);  /* sprite tile data at $2000 */
+  vdp_write_reg(7,  0x00);
+  vdp_write_reg(8,  0x00);
+  vdp_write_reg(9,  0x00);
+  vdp_write_reg(10, 0xFF);
+}
+
+/* ─── Palette + tile data ─────────────────────────────────────────── */
+/* SMS CRAM: 2-2-2 BGR. Entry 0 = backdrop. */
+static const uint8_t palette[32] = {
+  0x30, 0x0F, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,   /* BG: blue, yellow */
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,   /* sprite palette unused */
+  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+};
+
+/* One 8x8 tile, 4bpp interleaved (32 bytes = 8 rows × 4 planes per row).
+ * Only plane 0 has bits set → renders in color index 1 (yellow). */
+static const uint8_t tile_h[32] = {
+  0x66, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x7E, 0x00, 0x00, 0x00,
+  0x7E, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00,
+};
+
+/* ─── Upload helpers ──────────────────────────────────────────────── */
+static void load_palette(void) {
+  uint8_t i;
+  vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = palette[i];
+}
+
+static void load_tile(void) {
+  uint8_t i;
+  /* Tile 1 at VRAM offset 32 (= tile_idx * 32). Tile 0 left blank. */
+  vdp_set_addr(32, VDP_VRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_h[i];
+}
+
+static void clear_name_table(void) {
+  uint16_t i;
+  vdp_set_addr(0x3800, VDP_VRAM_WRITE);
+  /* 32 cols × 28 rows × 2 bytes = 1792 entries. */
+  for (i = 0; i < 1792; i++) PORT_VDP_DATA = 0;
+}
+
+static void place_h(void) {
+  /* Cell at row 13, col 15 (center-ish). */
+  vdp_set_addr(0x3800 + (13 * 32 + 15) * 2, VDP_VRAM_WRITE);
+  PORT_VDP_DATA = 1;       /* tile 1 */
+  PORT_VDP_DATA = 0;       /* no flips, BG palette, no priority */
+}
+
+static void wait_vblank(void) {
+  while ((PORT_VDP_CTRL & 0x80) == 0) { }
+}
+
+/* ─── main ───────────────────────────────────────────────────────── */
+void main(void) {
+  uint8_t scroll = 0;
+  uint8_t pressed;          /* C89: decls must precede statements */
+
+  vdp_init();
+  load_palette();
+  load_tile();
+  clear_name_table();
+  place_h();
+
+  /* Enable display: vblank IRQ on, display on, 192-line. */
+  vdp_write_reg(1, 0xE0);
+
+  /* Main loop. SDCC z80 is C89-only; all locals declared above.
+   * The do/while(1) shape works around an SDCC 4.4.0 register-
+   * allocation bug in `for(;;) { if (cond) f(literal, local); }`
+   * (the branchless update is what you'd write for max throughput
+   * on Z80 anyway). */
+  do {
+    wait_vblank();
+    /* Hold B1 to scroll the BG. */
+    pressed = (~PORT_JOY_A & JOY_B1) ? 1 : 0;
+    scroll = (uint8_t)(scroll + pressed);
+    vdp_write_reg(8, scroll);   /* R8 = BG X scroll */
+  } while (1);
+}

package/examples/sms/templates/default.c

@@ -0,0 +1,110 @@
+/* SMS hello-world. Writes a yellow 'H' tile to VRAM, places it in the
+ * name table, enables display. Pressing P1-B1 scrolls the BG by one
+ * pixel per frame.
+ *
+ * Single-file example — inlines the VDP helpers. For a more modular
+ * multi-file project, see `hello_sprite` and `tile_engine` templates
+ * (they pull in src/platforms/sms/lib/c/vdp_init.c, joypad_read.c,
+ * load_tiles.c, load_palette.c).
+ */
+#include <stdint.h>
+
+/* ─── SMS hardware ports ──────────────────────────────────────────── */
+__sfr __at 0xBE PORT_VDP_DATA;
+__sfr __at 0xBF PORT_VDP_CTRL;
+__sfr __at 0xDC PORT_JOY_A;
+
+#define VDP_VRAM_WRITE 0x40
+#define VDP_REG_WRITE  0x80
+#define VDP_CRAM_WRITE 0xC0
+#define JOY_B1         0x10
+
+static void vdp_write_reg(uint8_t reg, uint8_t value) {
+  PORT_VDP_CTRL = value;
+  PORT_VDP_CTRL = VDP_REG_WRITE | reg;
+}
+
+static void vdp_set_addr(uint16_t addr, uint8_t prefix) {
+  PORT_VDP_CTRL = (uint8_t)(addr & 0xFF);
+  PORT_VDP_CTRL = (uint8_t)((addr >> 8) & 0x3F) | prefix;
+}
+
+static void vdp_init(void) {
+  vdp_write_reg(0,  0x36);
+  vdp_write_reg(1,  0x80);
+  vdp_write_reg(2,  0xFF);
+  vdp_write_reg(3,  0xFF);
+  vdp_write_reg(4,  0xFF);
+  vdp_write_reg(5,  0xFF);
+  vdp_write_reg(6,  0xFB);
+  vdp_write_reg(7,  0x00);
+  vdp_write_reg(8,  0x00);
+  vdp_write_reg(9,  0x00);
+  vdp_write_reg(10, 0xFF);
+}
+
+static const uint8_t palette[32] = {
+  0x30, 0x0F, 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, 0x00, 0x00, 0x00, 0x00,
+};
+
+static const uint8_t tile_h[32] = {
+  0x66, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x7E, 0x00, 0x00, 0x00,
+  0x7E, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x66, 0x00, 0x00, 0x00,
+  0x00, 0x00, 0x00, 0x00,
+};
+
+static void load_palette(void) {
+  uint8_t i;
+  vdp_set_addr(0, VDP_CRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = palette[i];
+}
+
+static void load_tile(void) {
+  uint8_t i;
+  vdp_set_addr(32, VDP_VRAM_WRITE);
+  for (i = 0; i < 32; i++) PORT_VDP_DATA = tile_h[i];
+}
+
+static void clear_name_table(void) {
+  uint16_t i;
+  vdp_set_addr(0x3800, VDP_VRAM_WRITE);
+  for (i = 0; i < 1792; i++) PORT_VDP_DATA = 0;
+}
+
+static void place_h(void) {
+  vdp_set_addr(0x3800 + (13 * 32 + 15) * 2, VDP_VRAM_WRITE);
+  PORT_VDP_DATA = 1;
+  PORT_VDP_DATA = 0;
+}
+
+static void wait_vblank(void) {
+  while ((PORT_VDP_CTRL & 0x80) == 0) { }
+}
+
+void main(void) {
+  uint8_t scroll = 0;
+
+  vdp_init();
+  load_palette();
+  load_tile();
+  clear_name_table();
+  place_h();
+
+  vdp_write_reg(1, 0xE0);
+
+  do {
+    uint8_t pressed;
+    wait_vblank();
+    pressed = (~PORT_JOY_A & JOY_B1) ? 1 : 0;
+    scroll = (uint8_t)(scroll + pressed);
+    vdp_write_reg(8, scroll);
+  } while (1);
+}

package/examples/sms/templates/hello_sprite.c

@@ -0,0 +1,90 @@
+/* ── hello_sprite.c — SMS starter (one sprite + d-pad) ──────────────
+ *
+ * Drives one sprite around the SMS screen with the directional pad.
+ * Uses the bundled SMS runtime helpers (sms_vdp_init, sms_load_tiles,
+ * sms_load_palette, sms_sprite_*, sms_vblank_wait, sms_joypad_read).
+ *
+ * SMS hardware notes the templates assume:
+ *   - 256×192 visible area in mode 4
+ *   - Sprite attribute table at VRAM $3F00 (configured by sms_vdp_init)
+ *   - Sprite tile data at VRAM $2000 (R6 = 0xFB)
+ *   - 64 sprite slots × 4 bytes (Y / X / tile / unused)
+ *
+ * Multi-file project — main.c plus the runtime .c files. Build with:
+ *   buildSource({platform:"sms", language:"c",
+ *                sources: { "main.c": ..., "vdp_init.c": ..., ... },
+ *                includes: { "sms_hw.h": ... }})
+ *
+ * createProject({platform:"sms", template:"hello_sprite"}) copies all
+ * the bits into your project tree.
+ */
+#include "sms_hw.h"
+#include "sms_sfx.h"
+#include <stdint.h>
+
+extern void sms_vdp_init(void);
+extern void sms_vdp_display_on(void);
+extern void sms_vdp_write_reg(uint8_t reg, uint8_t value);
+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_vblank_wait(void);
+extern uint8_t sms_joypad_read(void);
+extern void sms_sprite_init(void);
+extern void sms_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
+extern void sms_sat_upload(void);
+
+/* BG palette: backdrop blue + yellow. Sprite palette (entries 16-31)
+ * we set white at index 17 so our sprite is visible.
+ * SMS CRAM is 2-2-2 BGR: 0x00=black, 0x3F=white. */
+static const uint8_t palette[32] = {
+  0x10,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x3F,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+};
+
+/* One 8×8 sprite tile (4bpp interleaved). Filled square in color 1. */
+static const uint8_t sprite_tile[32] = {
+  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,
+};
+
+void main(void) {
+  uint8_t x = 124;   /* mid-screen X */
+  uint8_t y = 88;    /* mid-screen Y */
+  uint8_t prev = 0;
+
+  sms_vdp_init();
+  sms_load_palette(palette);
+  /* Upload one sprite tile to VRAM $2000 (sprite tile area). */
+  sms_load_tiles(0x2000, sprite_tile, 32);
+
+  sms_sprite_init();
+  sfx_init();
+  sfx_tone(0, 220, 12);  /* boot chime — confirms sound works */
+  sms_sprite_set(0, x, y, /*tile*/ 0);
+  sms_sat_upload();
+
+  sms_vdp_display_on();
+
+  do {
+    uint8_t pad;
+    sms_vblank_wait();
+    sfx_update();
+    /* Stage sprite for the next frame BEFORE we read input — the SAT
+     * upload below pushes the staging buffer to VRAM at vblank. */
+    sms_sprite_set(0, x, y, 0);
+    sms_sat_upload();
+
+    pad = sms_joypad_read();
+    if (pad & JOY_LEFT  && x > 0)       x = (uint8_t)(x - 2);
+    if (pad & JOY_RIGHT && x < 248)     x = (uint8_t)(x + 2);
+    if (pad & JOY_UP    && y > 0)       y = (uint8_t)(y - 2);
+    if (pad & JOY_DOWN  && y < 184)     y = (uint8_t)(y + 2);
+    prev = pad;
+    (void)prev;
+  } while (1);
+}