romdevtools 0.13.0

package/examples/msx/music_sfx/main.c

@@ -0,0 +1,164 @@
+/* MSX music_sfx — AY-3-8910 PSG melody + trigger-fired sound effect.
+ *
+ * WHAT IT DOES
+ *   - Channel A plays a short looping 8-note melody (~0.2 s per note).
+ *   - Channel B plays a soft bass note under the melody (harmony).
+ *   - Pressing the joystick TRIGGER (button A / port-1 fire) fires a quick
+ *     descending "blip" SFX on channel C.
+ *   - On-screen state is shown with sprites: a row of eight "beat" sprites
+ *     lights the one matching the current melody step (a tiny step sequencer,
+ *     split across two rows so the VDP's 4-sprites-per-scanline limit doesn't
+ *     drop any), and a big 16x16 indicator sprite turns RED while the trigger
+ *     is held (white when idle).
+ *
+ * WHY SPRITES (not text): screen 2's font isn't loaded by INIGRP, so the most
+ * reliable "visible state" on a fresh graphic screen is sprites, which the VDP
+ * draws from the sprite tables with no font upload. The big indicator uses the
+ * VDP's 16x16 magnified sprite mode (R1 bits 0-1) so it's impossible to miss.
+ *
+ * KEY APIS (from msx_hw.h / msx_vdp.c, all direct-port, no fragile asm):
+ *   msx_psg_tone(chan, period, vol)  - play a square tone on PSG chan 0/1/2
+ *   msx_psg_off(chan)                - silence a channel
+ *   gttrig(1)                        - BIOS GTTRIG: bit7 set = trigger pressed
+ *   msx_set_sprite / msx_clear_sprites / msx_vblank_wait
+ *
+ * AY period for a note = clock(1789772.5) / (16 * freq). period 0 = silent.
+ *
+ * BUILD: link msx_vdp.c + msx_crt0.s (sources) + msx_hw.h (includes),
+ *        crt0 ".module empty\n", sourceName "main.c".
+ */
+#include "msx_hw.h"
+
+/* --- melody (channel A) ------------------------------------------------- */
+#define NOTE_C4 426
+#define NOTE_D4 379
+#define NOTE_E4 338
+#define NOTE_G4 284
+#define NOTE_A4 253
+#define NOTE_C5 213
+#define REST    0
+
+#define MELODY_LEN 8
+static const unsigned int MELODY[MELODY_LEN] = {
+    NOTE_C4, NOTE_E4, NOTE_G4, NOTE_C5, NOTE_A4, NOTE_G4, NOTE_E4, NOTE_D4
+};
+/* a slow bass line on channel B, one note per two melody steps */
+static const unsigned int BASS[MELODY_LEN] = {
+    NOTE_C4 * 2, NOTE_C4 * 2, NOTE_E4 * 2, NOTE_E4 * 2,
+    NOTE_C4 * 2, NOTE_C4 * 2, NOTE_G4 * 2, NOTE_G4 * 2
+};
+
+/* note duration in frames (~60 Hz). 12 frames ~= 0.2 s. */
+#define NOTE_FRAMES 12
+
+/* --- sprite patterns ---------------------------------------------------- */
+/* Pattern 0: a solid 8x8 blob used for the small "beat" markers. */
+static const unsigned char BLOB8[8] = {
+    0x3C, 0x7E, 0xFF, 0xFF, 0xFF, 0xFF, 0x7E, 0x3C
+};
+/* Patterns 1..4: a 16x16 ring used as the big trigger indicator. A 16x16 MSX
+ * sprite is four 8x8 patterns laid out TL,BL,TR,BR (column-major). */
+static const unsigned char RING16[32] = {
+    /* pattern 1 = top-left quadrant */
+    0x03, 0x0C, 0x10, 0x20, 0x40, 0x40, 0x80, 0x80,
+    /* pattern 2 = bottom-left quadrant */
+    0x80, 0x80, 0x40, 0x40, 0x20, 0x10, 0x0C, 0x03,
+    /* pattern 3 = top-right quadrant */
+    0xC0, 0x30, 0x08, 0x04, 0x02, 0x02, 0x01, 0x01,
+    /* pattern 4 = bottom-right quadrant */
+    0x01, 0x01, 0x02, 0x02, 0x04, 0x08, 0x30, 0xC0
+};
+
+/* Sprite planes:
+ *   0      = big 16x16 trigger indicator
+ *   1..8   = the eight small beat markers (step sequencer)            */
+#define PLANE_INDICATOR 0
+#define PLANE_BEAT0     1
+
+/* MSX sprite colours (fixed TMS9918 palette): 15=white, 8=red, 4=blue,
+ * 11=light yellow, 14=gray. */
+#define COL_WHITE  15
+#define COL_RED     8
+#define COL_GREEN   3
+#define COL_GRAY   14
+#define COL_YELLOW 11
+
+/* Beat-marker placement. The TMS9918/V9938 only draws 4 sprites per scanline;
+ * with all eight on one row the 5th-8th would vanish. So we stagger them into
+ * two rows of four (even index -> top row, odd -> bottom row), and within each
+ * row spread them out horizontally. */
+#define BEAT_X(i) ((unsigned char)(72 + ((i) >> 1) * 28))
+#define BEAT_Y(i) ((unsigned char)(((i) & 1) ? 168 : 144))
+
+void main(void) {
+    unsigned char step = 0;      /* current melody / beat index 0..7 */
+    unsigned char ticks = 0;     /* frames elapsed on the current note */
+    unsigned int  sfx = 0;       /* sfx period; 0 = not playing       */
+    unsigned char trig, prev_trig = 0;
+    unsigned char i;
+
+    msx_set_screen2();           /* 256x192 graphic mode, display on  */
+    msx_clear_sprites();
+
+    /* Enable 16x16 sprites (R1 bit1 = size 16x16). Keep display on (bit6) and
+     * the standard mode bits INIGRP set; just OR in the size bit. R1 after
+     * INIGRP is 0x60 -> 0x62 selects 16x16 unmagnified sprites. */
+    msx_wrtvdp(1, 0x62);
+
+    /* Upload sprite patterns: BLOB8 at pattern #0, RING16 at patterns #1..#4
+     * (each pattern is 8 bytes; pattern N lives at SPRPAT + N*8). */
+    msx_vram_write(VRAM_SPRPAT + 0 * 8, BLOB8, 8);
+    msx_vram_write(VRAM_SPRPAT + 1 * 8, RING16, 32);
+
+    /* Lay out the eight beat markers in a row near the bottom. With 16x16
+     * sprites the small BLOB8 (pattern 0) draws as a 16x16 magnified-ish block;
+     * that's fine — we want them chunky and visible. Pattern numbers for a
+     * 16x16 sprite must be multiples of 4, so BLOB8 (pattern 0) is valid and
+     * the ring starts at pattern 4... but we uploaded the ring at pattern 1.
+     * To keep both valid in 16x16 mode we give the beat markers pattern 0 and
+     * the indicator pattern 4-aligned; re-upload the ring to pattern 4. */
+    msx_vram_write(VRAM_SPRPAT + 4 * 8, RING16, 32);
+
+    for (i = 0; i < MELODY_LEN; i++) {
+        msx_set_sprite((unsigned char)(PLANE_BEAT0 + i),
+                       BEAT_X(i), BEAT_Y(i),
+                       0 /*BLOB8*/, COL_GRAY);
+    }
+
+    for (;;) {
+        /* --- melody (chan A) + bass (chan B): advance every NOTE_FRAMES --- */
+        if (ticks == 0) {
+            if (MELODY[step] == REST) msx_psg_off(0);
+            else                      msx_psg_tone(0, MELODY[step], 13);
+            msx_psg_tone(1, BASS[step], 7);   /* quiet bass */
+
+            /* light the current beat (yellow), dim the rest (gray) */
+            for (i = 0; i < MELODY_LEN; i++) {
+                msx_set_sprite((unsigned char)(PLANE_BEAT0 + i),
+                               BEAT_X(i), BEAT_Y(i),
+                               0,
+                               (i == step) ? COL_YELLOW : COL_GRAY);
+            }
+            step = (unsigned char)((step + 1) & (MELODY_LEN - 1));
+        }
+        ticks = (unsigned char)((ticks + 1) % NOTE_FRAMES);
+
+        /* --- SFX (chan C): fire a descending blip on the trigger PRESS edge --- */
+        trig = gttrig(1);                       /* bit7 set = pressed */
+        if ((trig & 0x80) && !(prev_trig & 0x80)) {
+            sfx = 120;                          /* start high, slide down */
+        }
+        prev_trig = trig;
+        if (sfx) {
+            msx_psg_tone(2, sfx, 14);
+            sfx += 40;                          /* period grows -> pitch falls */
+            if (sfx > 800) { sfx = 0; msx_psg_off(2); }
+        }
+
+        /* --- big indicator sprite: RED while trigger held, else WHITE --- */
+        msx_set_sprite(PLANE_INDICATOR, 120, 70, 4 /*RING16*/,
+                       (unsigned char)((trig & 0x80) ? COL_RED : COL_WHITE));
+
+        msx_vblank_wait();
+    }
+}

package/examples/msx/sprite_move/README.md

@@ -0,0 +1,44 @@
+# MSX — sprite_move
+
+A joystick-controlled **16x16 sprite over a screen-2 TILED background**. A
+checkerboard of two tile patterns (a framed grid cell + a centre dot) fills the
+whole 32x24 name table; the d-pad moves a white sprite over it and clamps it to
+the visible area. The minimal "draw a real tiled background → read input → move a
+sprite" loop every action game starts from.
+
+**Build** (link the helper lib + cart crt0):
+```
+buildForPlatform({
+  platform: "msx",
+  sources:  { "main.c": <main.c>, "msx_vdp.c": <lib>, "msx_crt0.s": <crt0> },
+  includes: { "msx_hw.h": <header> },
+  crt0: ".module empty\n",
+  sourceName: "main.c",
+})
+```
+Helper lib + crt0 live in `src/platforms/msx/lib/c/`.
+
+## What it shows
+
+- **Tiled background** — `draw_background()` uploads two 8x8 patterns + their
+  colour bytes into all THREE screen-2 pattern/colour banks (one per vertical
+  third), then lays a checkerboard into the name table. Screen 2 is the classic
+  MSX tiled mode: the colour table is one fg/bg byte per 8-pixel row.
+- **16x16 sprite** — set VDP R1 to `0xE2` (display-on + 16K + size-16x16) and
+  upload a 32-byte sprite pattern (four 8x8 quadrants in column order). Pattern
+  `#0` is what `msx_set_sprite(0, x, y, 0, 15)` selects.
+- **Input + clamp** — `msx_read_joystick(1)` returns 0=center, 1-8 clockwise
+  from up; the code maps the diagonals and clamps px/py to the screen edges.
+
+## Verified
+
+Boot ≥300 frames past the C-BIOS logo, then drive input. Holding RIGHT+DOWN
+clamps the sprite to the bottom-right `(x=238, y=174)`; LEFT+UP clamps it to the
+top-left `(x=2, y=2)`. Read back from VRAM sprite-attr at `0x1B00` (region
+`msx_vram`): Y, X, pattern, colour.
+
+**Input gotcha (verified against the bluemsx core):** the C code reads MSX
+joystick **1** (`msx_read_joystick(1)` → BIOS GTSTCK), and that maps to libretro
+retropad **port 0** — i.e. `host.setInput({ ports: [{ right: true }] })` (the
+FIRST port entry) drives the sprite. Joystick **0** is the keyboard cursor, which
+a gamepad does NOT drive. Don't put the d-pad on `ports[1]`; it's a no-op here.

package/examples/msx/sprite_move/main.c

@@ -0,0 +1,100 @@
+/* MSX sprite_move — a joystick-controlled sprite over a screen-2 TILED background.
+ *
+ * A checkerboard of two tile patterns fills the whole 32x24 screen-2 name table,
+ * and a 16x16 sprite (four 8x8 cells, VDP "size 1 = 16x16") moves over it with the
+ * joystick. The sprite clamps to the visible area. This is the minimal
+ * "draw a real tiled background + read input + move a sprite" loop every action
+ * game starts from.
+ *
+ * Why a 16x16 sprite: screen-2 sprites default to 8x8; we set VDP R1 bit 1 (SI)
+ * to get 16x16, whose pattern is four 8x8 quadrants stored as 32 consecutive
+ * bytes (top-left col, bottom-left col, top-right col, bottom-right col).
+ *
+ * Build: buildForPlatform({ platform:"msx",
+ *   sources:{ "main.c":..., "msx_vdp.c":..., "msx_crt0.s":... },
+ *   includes:{ "msx_hw.h":... }, crt0:".module empty\n", sourceName:"main.c" })
+ */
+#include "msx_hw.h"
+
+/* ── Background tile patterns (8x8, 1bpp; a bit set = foreground colour) ──────
+ * tile 0: a framed block (outline) — reads as a grid cell.
+ * tile 1: a small centre dot — the alternating checkerboard cell. */
+static const unsigned char TILE_FRAME[8] = {
+    0xFF, 0x81, 0x81, 0x81, 0x81, 0x81, 0x81, 0xFF
+};
+static const unsigned char TILE_DOT[8] = {
+    0x00, 0x00, 0x18, 0x3C, 0x3C, 0x18, 0x00, 0x00
+};
+
+/* ── Colour bytes (one per 8-pixel tile row): high nibble = fg, low = bg ──────
+ * TMS9918 fixed palette: 4=dark blue, 5=light blue, 6=dark red, 14=grey,
+ * 15=white, 1=transparent/black. */
+#define COL_FRAME 0xF4   /* white frame on dark-blue field   */
+#define COL_DOT   0x54   /* light-blue dot on dark-blue field */
+
+/* ── 16x16 sprite: a filled blob with an outline, stored as 4 quadrants ───────
+ * VDP 16x16 layout = 32 bytes: bytes 0-7 = left half rows 0-7,
+ * 8-15 = left half rows 8-15, 16-23 = right half rows 0-7, 24-31 = right rows 8-15. */
+static const unsigned char SPR_BLOB[32] = {
+    /* left half, top    */ 0x07, 0x1F, 0x3F, 0x7F, 0x7F, 0xFF, 0xFF, 0xFF,
+    /* left half, bottom */ 0xFF, 0xFF, 0xFF, 0x7F, 0x7F, 0x3F, 0x1F, 0x07,
+    /* right half, top   */ 0xE0, 0xF8, 0xFC, 0xFE, 0xFE, 0xFF, 0xFF, 0xFF,
+    /* right half, bottom*/ 0xFF, 0xFF, 0xFF, 0xFE, 0xFE, 0xFC, 0xF8, 0xE0
+};
+
+/* Lay a checkerboard of tile 0 / tile 1 across all 32x24 name-table cells. */
+static void draw_background(void) {
+    unsigned char row, col;
+    /* Pattern + colour generators: screen 2 has THREE 256-tile banks (one per
+     * vertical third). We only use tiles 0 and 1, so write them into all three
+     * banks at base + third*0x800 so the whole screen shares the same art. */
+    unsigned char third;
+    for (third = 0; third < 3; third++) {
+        unsigned int poff = (unsigned int)third * 0x800;
+        /* pattern bytes for tile 0 and tile 1 */
+        msx_vram_write((unsigned int)(VRAM_PATTERN + poff +  0), TILE_FRAME, 8);
+        msx_vram_write((unsigned int)(VRAM_PATTERN + poff +  8), TILE_DOT,   8);
+        /* colour bytes — 8 rows each, constant per tile */
+        msx_fill_vram((unsigned int)(VRAM_COLOR + poff +  0), 8, COL_FRAME);
+        msx_fill_vram((unsigned int)(VRAM_COLOR + poff +  8), 8, COL_DOT);
+    }
+    /* Name table: checkerboard of tile 0 / tile 1. */
+    for (row = 0; row < 24; row++) {
+        for (col = 0; col < 32; col++) {
+            unsigned int cell = VRAM_NAME + (unsigned int)row * 32 + col;
+            msx_fill_vram(cell, 1, (unsigned char)((row + col) & 1));
+        }
+    }
+}
+
+void main(void) {
+    unsigned char px = 120, py = 88;   /* sprite top-left position */
+    unsigned char dir;
+
+    msx_set_screen2();                 /* 256x192 graphic mode, display on */
+    msx_clear_sprites();
+
+    /* Switch sprites to 16x16 (VDP R1: keep display-on bit 6 + 16K bit 7 that
+     * INIGRP set, add bit 1 = size 16x16). INIGRP leaves R1 = 0xE2 on MSX2;
+     * 0xE2 | 0x02 = 0xE2 already has size; set explicitly to be safe. */
+    msx_wrtvdp(1, 0xE2);               /* 0x40 disp-on | 0x80 16K | 0x02 16x16 */
+
+    msx_vram_write(VRAM_SPRPAT, SPR_BLOB, 32);  /* 16x16 sprite, pattern #0 */
+    draw_background();
+
+    for (;;) {
+        /* Port 1 = the joystick port (port 0 is the keyboard cursor, which an
+         * emulator's gamepad does NOT drive). 0=center, 1-8 clockwise from up. */
+        dir = msx_read_joystick(1);
+        if (dir == 8 || dir == 1 || dir == 2) { if (py > 2)   py -= 2; }
+        if (dir == 4 || dir == 5 || dir == 6) { if (py < 174) py += 2; }
+        if (dir == 6 || dir == 7 || dir == 8) { if (px > 2)   px -= 2; }
+        if (dir == 2 || dir == 3 || dir == 4) { if (px < 238) px += 2; }
+
+        /* Plane 0, pattern 0, colour 15 = white. (16x16 sprite uses pattern *4
+         * indices internally; pattern #0 maps to the 32-byte block we uploaded.) */
+        msx_set_sprite(0, px, py, 0, 15);
+
+        msx_vblank_wait();
+    }
+}

package/examples/nes/main.c

@@ -0,0 +1,143 @@
+/* Hello, NES — a real hello-world scaffold, not just while(1) {}.
+ *
+ * What this does:
+ *   1. Disables PPU during init (avoids race with first frame).
+ *   2. Uploads a 4-color palette.
+ *   3. Writes a single 8x8 tile (a yellow 'H') into CHR-RAM.
+ *   4. Drops a single sprite into shadow OAM ($0200..) — the NMI
+ *      handler DMAs it to the PPU every vblank.
+ *   5. Enables the PPU and loops forever (NMI does all the real work).
+ *
+ * BUILD: this file expects linkerConfig: "chr-ram" so the CHR-RAM
+ * region is writable at runtime. Pass it to buildSource:
+ *
+ *   buildSource({
+ *     platform: "nes",
+ *     language: "c",
+ *     linkerConfig: "chr-ram",
+ *     sources: {
+ *       "main.c": <this file>,
+ *     },
+ *   });
+ *
+ * The chr-ram preset auto-includes a custom crt0 that emits an iNES
+ * header with CHR-RAM=0, points the NMI vector at a `nmi: rti` stub.
+ * To install a real NMI handler, add nmi_handler.c + nmi_trampoline.s
+ * from getStarterSnippet and modify the crt0 to drop its `nmi:` line
+ * (see those snippets' comments for the exact edits).
+ *
+ * cc65 IS C89: declare loop variables at the top of blocks, no //
+ * comments inside some contexts, no s16/uint64_t (cc65 stdint.h covers
+ * uint8/16/32 and int8/16/32 only). Use C89 idioms or you'll get
+ * 200+ errors on first build.
+ */
+
+#include <stdint.h>
+
+/* PPU registers. */
+#define PPUCTRL    (*(volatile uint8_t*)0x2000)
+#define PPUMASK    (*(volatile uint8_t*)0x2001)
+#define PPUSTATUS  (*(volatile uint8_t*)0x2002)
+#define PPUADDR    (*(volatile uint8_t*)0x2006)
+#define PPUDATA    (*(volatile uint8_t*)0x2007)
+#define OAMADDR    (*(volatile uint8_t*)0x2003)
+#define OAMDMA     (*(volatile uint8_t*)0x4014)
+
+/* Shadow OAM — DMA'd to PPU sprite RAM every vblank by the NMI. */
+#pragma bss-name(push, "OAM")
+uint8_t oam[256];
+#pragma bss-name(pop)
+
+/* Tile 1 — an 8x8 'H' glyph. NES tiles are 2bpp (16 bytes per tile:
+ * 8 bytes plane 0, 8 bytes plane 1). For a 1-color glyph we use plane
+ * 0 only; plane 1 is all zeros. */
+static const uint8_t tile_H[16] = {
+    /* plane 0: shape */
+    0b10000010,
+    0b10000010,
+    0b10000010,
+    0b11111110,
+    0b10000010,
+    0b10000010,
+    0b10000010,
+    0b00000000,
+    /* plane 1: empty (color stays in palette 0) */
+    0,0,0,0,0,0,0,0,
+};
+
+/* Palette: 4 colors per palette × 4 sprite palettes + 4 BG palettes. */
+static const uint8_t palette[32] = {
+    /* BG palette 0..3 (4 colors each) */
+    0x0F, 0x30, 0x10, 0x00,   /* gray-on-white */
+    0x0F, 0x21, 0x11, 0x01,   /* blue */
+    0x0F, 0x27, 0x17, 0x07,   /* orange */
+    0x0F, 0x2A, 0x1A, 0x0A,   /* green */
+    /* Sprite palette 0..3 (color 0 is transparent) */
+    0x0F, 0x28, 0x18, 0x08,   /* yellow — used by our sprite */
+    0x0F, 0x21, 0x11, 0x01,
+    0x0F, 0x27, 0x17, 0x07,
+    0x0F, 0x2A, 0x1A, 0x0A,
+};
+
+static void wait_vblank(void) {
+    /* Spin until bit 7 of PPUSTATUS is set, then reset latch. */
+    while ((PPUSTATUS & 0x80) == 0) { /* wait */ }
+}
+
+static void ppu_addr(uint16_t a) {
+    PPUSTATUS;             /* clear address latch */
+    PPUADDR = (uint8_t)(a >> 8);
+    PPUADDR = (uint8_t)(a & 0xFF);
+}
+
+void main(void) {
+    uint16_t i;
+
+    /* 1. Initial PPU off — disable rendering, NMI, IRQ. */
+    PPUCTRL = 0;
+    PPUMASK = 0;
+
+    /* 2. Wait two vblanks (NES init protocol — PPU warm-up). */
+    wait_vblank();
+    wait_vblank();
+
+    /* 3. Upload our tile to CHR-RAM at $0010 (tile index 1, sprite table). */
+    ppu_addr(0x0010);
+    for (i = 0; i < 16; i++) PPUDATA = tile_H[i];
+
+    /* 4. Upload palette to $3F00. */
+    ppu_addr(0x3F00);
+    for (i = 0; i < 32; i++) PPUDATA = palette[i];
+
+    /* 5. Init shadow OAM: hide all sprites (Y = $FF moves off screen). */
+    for (i = 0; i < 256; i += 4) {
+        oam[i + 0] = 0xFF;  /* Y */
+        oam[i + 1] = 0;     /* tile */
+        oam[i + 2] = 0;     /* attr */
+        oam[i + 3] = 0;     /* X */
+    }
+    /* Drop sprite 0 in the middle of the screen, using tile 1, sprite palette 0. */
+    oam[0] = 110;     /* Y */
+    oam[1] = 0x01;    /* tile index */
+    oam[2] = 0x00;    /* attrs: palette 0, no flip, in front */
+    oam[3] = 124;     /* X */
+
+    /* 6. Reset scroll. */
+    ppu_addr(0x2000);
+    PPUSTATUS;
+    /* Scroll regs would go here (write to $2005) if we wanted to scroll. */
+
+    /* 7. One-shot OAM DMA now (NMI will keep doing this every frame
+     *    if you install an NMI handler — see nmi_handler.c). */
+    OAMADDR = 0;
+    OAMDMA = 0x02;  /* DMA from $0200 */
+
+    /* 8. Enable rendering: show sprites, leftmost 8px shown. */
+    PPUMASK = 0x1E;
+    /* PPUCTRL = $80 to enable NMI; leaving disabled for this minimal
+     * scaffold so vblank doesn't fire (we don't have an NMI handler
+     * installed). The screen will just sit showing the sprite.
+     * Add NMI later via nmi_handler.c. */
+
+    while (1) { /* park here forever */ }
+}

package/examples/nes/space-shooter/README.md

@@ -0,0 +1,69 @@
+# NES space-shooter — canonical "NES-shaped C" reference
+
+A complete, runnable NES game in C (~440 lines) — a generic fixed-shooter
+(player cannon vs. a descending alien grid, with shields and a HUD) that
+demonstrates how to work *within* the NES's hard constraints instead of
+fighting them. Fork this when you want a real game structure, not just a
+hello-world. (Original example in the shoot-the-aliens *genre* — not a clone of
+any specific commercial title.)
+
+## Build
+
+```
+build({
+  output: 'rom',
+  platform: "nes",
+  language: "c",
+  sources: { "main.c": ..., "nes_runtime.c": ... },
+  includes: { "nes_runtime.h": ... },
+  linkerConfig: "chr-ram-runtime"
+})
+```
+
+Use the **`chr-ram-runtime`** preset (not bare `chr-ram`): it bundles the crt0
+(iNES header + reset vector), the NMI handler that DMAs shadow OAM each vblank,
+and the `_shadow_oam` definition this game's `oam_spr`/`oam_clear` rely on. The
+bare `chr-ram` preset has only an `nmi: rti` stub and no `_shadow_oam`, so it
+fails to link here. Don't add your own crt0 source either — the preset supplies
+it (a second one causes `Duplicate external identifier: __STARTUP__`). Produces
+a 32 KB NROM `.nes` (CHR-RAM — tiles uploaded at runtime, no CHR-ROM bank). Check the `ramUsage` field in the build response: this game runs
+at **BSS ≈ 371 B** of the ~512 B normal-RAM budget — comfortably under, but a
+good illustration of how tight NES RAM is.
+
+## What it teaches (the NES constraints, made concrete)
+
+- **Tiny RAM → bit-packed state.** All 20 aliens live in `uint8_t
+  alien_alive_mask[4]` (one bit per column), not a 20-byte array. Everything is
+  `uint8_t`/`int8_t`; there are no large structs. This is *why* NES C looks the
+  way it does — the ~512 B BSS ceiling forces it.
+- **8-sprites-per-scanline limit → 5 alien columns.** The formation is 5 wide on
+  purpose so a row never exceeds the hardware's per-scanline sprite cap (which
+  would otherwise drop/flicker sprites). Wide-but-shallow beats tall-and-narrow.
+- **OAM staging order.** `stage_sprites()` (which calls `oam_clear` + `oam_spr`)
+  runs **before** `ppu_wait_nmi()` in the main loop. The NMI handler DMAs shadow
+  OAM → real OAM at the *start* of vblank, so sprites must be staged before you
+  wait. Staging after `ppu_wait_nmi()` is the #1 "sprites flicker/vanish" bug.
+- **Sprites vs background, split by job.** Moving things (player, aliens, shots)
+  are OAM sprites; static structure (shields, HUD score/wave/lives) are
+  background tiles written with `tile_set`. Shields erode by swapping their BG
+  tile as `hp` drops.
+- **CHR-RAM upload.** `chr_ram_upload()` writes the tile bitmaps into both
+  pattern tables at boot (NROM CHR-RAM has no tiles until you do).
+- **APU SFX.** `sound_play_tone` / `sound_play_noise` for shoot / hit / death —
+  fire-and-forget, no music driver needed.
+
+## The main loop shape (copy this)
+
+```c
+for (;;) {
+  stage_sprites();   /* oam_clear + oam_spr — BEFORE the wait */
+  ppu_wait_nmi();    /* NMI DMAs shadow OAM at vblank start */
+  pad = pad_poll(0);
+  update_game(pad);  /* logic runs after vblank, off the hot path */
+  draw_hud();
+}
+```
+
+Game logic (movement, collision, spawning) runs *after* `ppu_wait_nmi()` so it
+happens during the visible frame, not during vblank — keeps the vblank window
+free for the DMA + any tile writes.