romdev-mcp 0.1.1

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
+   `getPlatformDoc`) before writing its render layer — they lead with that
+   platform's specific footgun.
+4. **Verify visually, not just by exit code.** `runSource` returns a screenshot;
+   `inspectSprites` / `getRenderingContext` / `readMemory` 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);
+}

package/examples/sms/templates/music_demo.c

@@ -0,0 +1,151 @@
+/* ── music_demo.c — SMS continuous 3-voice music demo ────────────────
+ *
+ * Plays a hand-authored 3-voice C-major loop forever via sms_music.{h,c}.
+ * Voice 0 carries the melody on PSG channel 0, voice 1 the harmony on
+ * channel 1, voice 2 the bass on channel 2. Noise channel 3 is left
+ * silent so a game built on top of this can still call sfx_noise for
+ * one-shot hits without colliding with the music driver.
+ *
+ * Display: writes the text "SMS MUSIC DEMO" centered on the BG plane
+ * using a tiny hand-authored 8×8 font (only the letters we need —
+ * SMUICDEO + space — so we burn a single tile per glyph and reference
+ * them by name-table index).
+ *
+ * Build via createProject({platform:"sms", template:"music_demo"}) or
+ * buildSource({platform:"sms", language:"c", sources:{ "main.c": ...,
+ * "sms_music.c": ... , ...runtime... }}).
+ */
+
+#include "sms_hw.h"
+#include "sms_music.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_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
+extern void sms_vblank_wait(void);
+
+/* BG palette: backdrop dark blue, fg colour 1 = bright cyan, colour 2 = yellow.
+ * SMS CRAM is 2-2-2 BGR — 0x30 = bright blue, 0x3F = white, 0x0F = yellow. */
+static const uint8_t palette[32] = {
+  0x20, 0x3F, 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,
+};
+
+/* 8×8 4bpp-interleaved tiles. Each tile = 32 bytes (8 rows × 4 planes).
+ * We only set plane 0 (the low colour bit), so each lit pixel reads as
+ * palette index 1 (bright cyan). Plane bytes 1/2/3 stay 0. Layout per
+ * row: { plane0, plane1, plane2, plane3 } = { row_byte, 0, 0, 0 }.
+ *
+ * Tile 0 is BLANK (used to clear the name table). Then one tile per
+ * needed glyph. Index assignment below feeds the name-table writes.
+ */
+static const uint8_t font_tiles[] = {
+  /* tile 0 — blank */
+  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,0x00,0x00,
+
+  /* tile 1 — 'S' */
+  0x3C,0x00,0x00,0x00, 0x66,0x00,0x00,0x00,
+  0x60,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+  0x06,0x00,0x00,0x00, 0x06,0x00,0x00,0x00,
+  0x66,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+
+  /* tile 2 — 'M' */
+  0xC3,0x00,0x00,0x00, 0xE7,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xDB,0x00,0x00,0x00,
+  0xC3,0x00,0x00,0x00, 0xC3,0x00,0x00,0x00,
+  0xC3,0x00,0x00,0x00, 0xC3,0x00,0x00,0x00,
+
+  /* tile 3 — 'U' */
+  0x66,0x00,0x00,0x00, 0x66,0x00,0x00,0x00,
+  0x66,0x00,0x00,0x00, 0x66,0x00,0x00,0x00,
+  0x66,0x00,0x00,0x00, 0x66,0x00,0x00,0x00,
+  0x66,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+
+  /* tile 4 — 'I' */
+  0x3C,0x00,0x00,0x00, 0x18,0x00,0x00,0x00,
+  0x18,0x00,0x00,0x00, 0x18,0x00,0x00,0x00,
+  0x18,0x00,0x00,0x00, 0x18,0x00,0x00,0x00,
+  0x18,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+
+  /* tile 5 — 'C' */
+  0x3C,0x00,0x00,0x00, 0x66,0x00,0x00,0x00,
+  0x60,0x00,0x00,0x00, 0x60,0x00,0x00,0x00,
+  0x60,0x00,0x00,0x00, 0x60,0x00,0x00,0x00,
+  0x66,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+
+  /* tile 6 — 'D' */
+  0xF8,0x00,0x00,0x00, 0xCC,0x00,0x00,0x00,
+  0xC6,0x00,0x00,0x00, 0xC6,0x00,0x00,0x00,
+  0xC6,0x00,0x00,0x00, 0xC6,0x00,0x00,0x00,
+  0xCC,0x00,0x00,0x00, 0xF8,0x00,0x00,0x00,
+
+  /* tile 7 — 'E' */
+  0xFE,0x00,0x00,0x00, 0xC0,0x00,0x00,0x00,
+  0xC0,0x00,0x00,0x00, 0xF8,0x00,0x00,0x00,
+  0xC0,0x00,0x00,0x00, 0xC0,0x00,0x00,0x00,
+  0xC0,0x00,0x00,0x00, 0xFE,0x00,0x00,0x00,
+
+  /* tile 8 — 'O' */
+  0x3C,0x00,0x00,0x00, 0x66,0x00,0x00,0x00,
+  0xC3,0x00,0x00,0x00, 0xC3,0x00,0x00,0x00,
+  0xC3,0x00,0x00,0x00, 0xC3,0x00,0x00,0x00,
+  0x66,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+};
+
+/* Tile indices for each char in our message — 'S' 'M' 'S' ' ' 'M' 'U'
+ * 'S' 'I' 'C' ' ' 'D' 'E' 'M' 'O'. 14 cells total. */
+static const uint8_t message[14] = {
+  1, 2, 1, 0,    /* "SMS " */
+  2, 3, 1, 4, 5, /* "MUSIC" */
+  0,             /* " " */
+  6, 7, 2, 8,    /* "DEMO" */
+};
+
+static void clear_name_table(void) {
+  uint8_t row;
+  uint8_t col;
+  for (row = 0; row < 28; row++) {
+    for (col = 0; col < 32; col++) {
+      sms_set_tilemap_cell(row, col, 0, 0);
+    }
+  }
+}
+
+static void draw_message(void) {
+  uint8_t i;
+  uint8_t row = 11;
+  uint8_t col = 9;     /* (32 - 14) / 2 = 9 → roughly centered */
+  for (i = 0; i < 14; i++) {
+    sms_set_tilemap_cell(row, (uint8_t)(col + i), message[i], 0);
+  }
+}
+
+void main(void) {
+  sms_vdp_init();
+  sms_load_palette(palette);
+  /* BG tiles at VRAM $0000 (R4 = 0xFF, set by sms_vdp_init). */
+  sms_load_tiles(0x0000, font_tiles, (uint16_t)sizeof(font_tiles));
+
+  clear_name_table();
+  draw_message();
+
+  music_init();
+  music_play(0);
+
+  sms_vdp_display_on();
+
+  do {
+    sms_vblank_wait();
+    music_update();
+  } while (1);
+}