romdev-mcp 0.1.1

package/examples/gba/templates/tonc_hello_sprite.c

@@ -0,0 +1,109 @@
+/* ── tonc_hello_sprite.c — Game Boy Advance Tonc sprite + d-pad ─────
+ *
+ * One 8×8 sprite driven by the d-pad. The canonical Tonc-tutorial
+ * pattern (every sprite chapter in gbadev.net/tonc opens with this
+ * shape).
+ *
+ * Hardware notes:
+ *   - 4bpp sprite tiles live at $06010000-$06017FFF (32 KB)
+ *   - OAM (object attribute memory) at $07000000 — 128 sprites × 8 B
+ *   - Each OBJ_ATTR is 8 bytes: attr0 (Y/shape/256-col), attr1
+ *     (X/affine/size), attr2 (tile/priority/palette), filler
+ *   - Sprite palette at $05000200-$050003FF (256 colors)
+ *
+ * Tonc API used:
+ *   - tile4_t / TILE4              4bpp tile bitmap type
+ *   - tile_mem[4][0]               first sprite tile slot
+ *   - pal_obj_mem                  sprite palette memory
+ *   - REG_DISPCNT                  display control
+ *   - DCNT_MODE0 | DCNT_OBJ | DCNT_OBJ_1D   tile BG + sprites + linear OAM mapping
+ *   - oam_init() + obj_buffer[]    shadow OAM + flush helper
+ *   - obj_set_attr / obj_set_pos   sprite attribute helpers
+ *   - oam_copy()                   shadow → real OAM (via DMA)
+ *   - key_poll() + key_held(KEY_*)  input
+ *   - VBlankIntrWait               frame heartbeat
+ */
+
+#include <tonc.h>
+#include "gba_sfx.h"
+
+/* A simple 8×8 sprite tile — colour 1 filled square. Each row of a
+ * 4bpp tile is 4 bytes (8 pixels × 4 bits = 32 bits). All-1s = every
+ * pixel uses palette index 1. */
+static const u32 sprite_tile[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+
+/* Shadow OAM. Tonc's recommended pattern: allocate your own 128-slot
+ * buffer in WRAM, mutate it freely each frame, then oam_copy to push
+ * the changes to OAM hardware via DMA. */
+static OBJ_ATTR obj_buffer[128];
+
+int main(void) {
+    int x = 120, y = 80;
+
+    /* ── Sprite tile data ─────────────────────────────────────────
+     * Upload our tile into the FIRST sprite tile slot (object tile
+     * area at char base 4, tile 0). tile_mem[4] is the OBJ char
+     * base, [0] is the tile index. tonccpy is Tonc's VRAM-safe
+     * memcpy (only does 16/32-bit writes — VRAM hates byte writes). */
+    tonccpy(&tile_mem[4][0], sprite_tile, sizeof(sprite_tile));
+
+    /* ── Sprite palette ───────────────────────────────────────────
+     * pal_obj_mem[i] = colour i in the sprite palette. Index 0 is
+     * always transparent for sprites; index 1 = bright cyan. */
+    pal_obj_mem[1] = CLR_CYAN;
+
+    /* ── OAM shadow init + place sprite 0 at (x, y) ───────────────
+     * oam_init clears the 128-slot shadow buffer (hides every
+     * sprite). Then we configure sprite 0 with:
+     *   attr0: y + 8x8 shape (ATTR0_SQUARE) + regular (non-affine)
+     *   attr1: x + tiny size (ATTR1_SIZE_8 = 8x8 within the square)
+     *   attr2: tile 0, priority 0, palette 0
+     */
+    oam_init(obj_buffer, 128);
+
+    /* ── IRQ setup ── REQUIRED for VBlankIntrWait() to work ──────
+     * Without this, the BIOS halts the CPU on the first
+     * VBlankIntrWait() forever (it waits for an IRQ that never
+     * fires). Single most common GBA-Tonc gotcha. */
+    irq_init(NULL);
+    irq_add(II_VBLANK, NULL);
+
+    /* Tiny boot chime so it's obvious sound is working from frame 1. */
+    sfx_init();
+    sfx_tone(1, 1700, 8);
+
+    obj_set_attr(&obj_buffer[0],
+        ATTR0_SQUARE,
+        ATTR1_SIZE_8,
+        ATTR2_PALBANK(0) | 0);
+    obj_set_pos(&obj_buffer[0], x, y);
+
+    /* ── Display setup ───────────────────────────────────────────
+     * DCNT_MODE0  — tiled mode (so BG0..3 are tile maps)
+     * DCNT_OBJ    — enable sprites
+     * DCNT_OBJ_1D — linear OAM tile addressing (vs the 2D matrix
+     *               layout that's almost always wrong) */
+    REG_DISPCNT = DCNT_MODE0 | DCNT_OBJ | DCNT_OBJ_1D;
+
+    /* ── Game loop ───────────────────────────────────────────────
+     * key_poll() updates the key state — call it once per frame.
+     * key_held(KEY_LEFT) etc. test current state. */
+    while (1) {
+        VBlankIntrWait();
+
+        key_poll();
+        if (key_held(KEY_LEFT)  && x > 0)   x--;
+        if (key_held(KEY_RIGHT) && x < 232) x++;
+        if (key_held(KEY_UP)    && y > 0)   y--;
+        if (key_held(KEY_DOWN)  && y < 152) y++;
+
+        obj_set_pos(&obj_buffer[0], x, y);
+
+        /* Flush all 128 OAM slots via DMA. Cheap; do it every frame. */
+        oam_copy(oam_mem, obj_buffer, 128);
+    }
+    return 0;
+}

package/examples/gbc/main.asm

@@ -0,0 +1,123 @@
+; Game Boy Color hello-world — yellow 'H' on a real BLUE background
+; (only possible on GBC; DMG can only do 4 shades).
+;
+; Differences from the DMG example:
+;   - byte at $0143 = $C0  → "GBC only" cart (boot ROM enables CGB mode)
+;   - palette via BCPS/BCPD ($FF68/$FF69), not BGP — full 15-bit BGR555
+;   - palette 0 entry 0 = backdrop (blue here), entry 1 = yellow
+;
+; Build with:
+;   buildSource({platform:"gbc", source: <this>})
+;
+; rgbfix is invoked automatically to fix the header checksums.
+
+SECTION "Entry", ROM0[$0100]
+  nop
+  jp Start
+
+  ; Nintendo logo bytes ($0104-$0133) — rgbfix fills these in.
+  ds $30, 0
+
+  ; Title ($0134-$0142, 15 bytes) — padded.
+  ds $0F, 0
+
+  ; $0143: CGB flag. $80 = CGB-supported, $C0 = CGB-only.
+  db $C0
+
+  ; Remainder of header — rgbfix patches checksums after assembly.
+  ds $014F - @ + 1, 0
+
+SECTION "Main", ROM0[$0150]
+
+Start:
+  ; ── Wait for vblank then turn LCD off ──────────────────────────
+.wait_vblank
+  ld a, [$FF44]
+  cp 144
+  jr c, .wait_vblank
+  xor a
+  ldh [$FF40], a
+
+  ld sp, $DFF0
+
+  ; ── Write GBC BG palette 0 ─────────────────────────────────────
+  ; BCPS = $FF68: bit 7 = auto-increment, bits 0-5 = byte index (0-63).
+  ; Each entry is 2 bytes BGR555: bbbbbggg gg_rrrrr.
+  ;
+  ; Palette layout: 8 palettes × 4 colors × 2 bytes = 64 bytes.
+  ; We write palette 0 entry 0 (backdrop=blue) and entry 1 (yellow).
+  ld a, $80                ; index 0, auto-increment ON
+  ldh [$FF68], a           ; BCPS
+  ld hl, BgPalette
+  ld b, 8                  ; first 4 entries = palette 0 (8 bytes)
+.pal_loop
+  ld a, [hl+]
+  ldh [$FF69], a           ; BCPD — auto-increments BCPS index
+  dec b
+  jr nz, .pal_loop
+
+  ; ── Upload one 'H' tile to VRAM bank 0, tile 1 ($8010) ─────────
+  ; The cartridge boots with VBK ($FF4F) = 0, so we're in bank 0.
+  ld hl, $8010
+  ld de, TileH
+  ld bc, 16
+.tile_loop
+  ld a, [de]
+  inc de
+  ld [hl+], a
+  dec bc
+  ld a, b
+  or c
+  jr nz, .tile_loop
+
+  ; ── Clear BG map (bank 0 = tile indices, bank 1 = attributes) ──
+  ld hl, $9800
+  ld bc, $400
+.clear_map
+  xor a
+  ld [hl+], a
+  dec bc
+  ld a, b
+  or c
+  jr nz, .clear_map
+
+  ; Tile attribute byte = 0 → palette 0, bank 0, no flip, no priority.
+  ; (We left bank 1 untouched, so all attributes are 0 — perfect.)
+
+  ; ── Write tile 1 to the center cell ────────────────────────────
+  ld hl, $9800 + (8 * 32) + 9
+  ld a, $01
+  ld [hl], a
+
+  ; ── Enable LCD ─────────────────────────────────────────────────
+  ld a, %10010001
+  ldh [$FF40], a
+
+  ; ── Idle ───────────────────────────────────────────────────────
+.idle
+  halt
+  nop
+  jr .idle
+
+; ── BG palette: 4 entries × 2 bytes (BGR555 little-endian) ──────
+; Color 0 = pure blue   ($7C00 = b=31, g=0, r=0)
+; Color 1 = pure yellow ($03FF = b=0, g=31, r=31)
+; Color 2 = unused      (black)
+; Color 3 = unused      (black)
+BgPalette:
+  dw $7C00     ; color 0: blue (backdrop)
+  dw $03FF     ; color 1: yellow
+  dw $0000     ; color 2
+  dw $0000     ; color 3
+
+; Tile data — same 'H' as the DMG example, color index 1 (yellow).
+; Plane 0 only → all H pixels = color 1.
+TileH:
+  db $66, $00   ; row 0
+  db $66, $00   ; row 1
+  db $66, $00   ; row 2
+  db $7E, $00   ; row 3
+  db $7E, $00   ; row 4
+  db $66, $00   ; row 5
+  db $66, $00   ; row 6
+  db $00, $00   ; row 7

package/examples/gbc/templates/default.c

@@ -0,0 +1,61 @@
+/* ── default.c — minimal Game Boy Color (CGB) starter ─────────────
+ *
+ * Boots the LCD, cycles a real CGB background palette via the BCPS
+ * + BCPD palette-RAM registers. Smallest possible "ROM that does
+ * something visible IN COLOR" — use this as the starting point when
+ * you want CGB-mode color, not DMG greyscale.
+ *
+ * GBC-specific notes:
+ *   - CGB uses BCPS/BCPD ($FF68/$FF69) to write into 64 bytes of
+ *     palette RAM (8 BG palettes × 4 colors × 2 bytes each, BGR555
+ *     little-endian). DMG-only BGP ($FF47) does nothing in CGB mode.
+ *   - patchGbHeader on a .gbc file sets $0143 = $80 (CGB-aware) by
+ *     default. The corresponding `.gb` default uses BGP — don't
+ *     cross-pollinate the two trees.
+ *   - This template is intentionally DIFFERENT from examples/gb/
+ *     templates/default.c — that one demonstrates DMG palettes.
+ *
+ * For something more game-shaped, peek at other templates in this dir:
+ *   - hello_sprite — sprite + d-pad movement
+ *   - tile_engine  — multi-room tile map with collision + transitions
+ *   - shmup / platformer / puzzle / sports / racing — genre scaffolds
+ *   - music_demo   — bundled hUGEDriver music driver demo
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+static const uint16_t palettes[4] = {
+  0x7FFF,  /* white */
+  0x3DEF,  /* light grey */
+  0x2108,  /* dark grey */
+  0x0000,  /* black */
+};
+
+void main(void) {
+  uint8_t i;
+  uint8_t shade = 0;
+  uint16_t frame = 0;
+
+  lcd_init_default();
+
+  /* Initial BG palette = all 4 entries cycle to the same shade. */
+  BCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    BCPD = (uint8_t)(palettes[shade] & 0xFF);
+    BCPD = (uint8_t)((palettes[shade] >> 8) & 0xFF);
+  }
+
+  for (;;) {
+    wait_vblank();
+    frame++;
+    if ((frame & 0x1F) == 0) {       /* every 32 frames */
+      shade = (shade + 1) & 0x03;
+      BCPS = 0x80;
+      for (i = 0; i < 4; i++) {
+        BCPD = (uint8_t)(palettes[shade] & 0xFF);
+        BCPD = (uint8_t)((palettes[shade] >> 8) & 0xFF);
+      }
+    }
+  }
+}

package/examples/gbc/templates/hello_sprite.c

@@ -0,0 +1,140 @@
+/* ── hello_sprite.c — GBC starter (works on plain GB too) ──────────
+ *
+ * A complete, tested, boots-from-cold game-loop skeleton:
+ *   - Turns the LCD off safely (handles "LCD already off at boot")
+ *   - Uploads one 16-byte tile to VRAM tile slot 1
+ *   - Writes a 4-color object palette (CGB BCPD path; harmless on DMG)
+ *   - Places sprite 0 in the middle of the screen
+ *   - Reads d-pad each vblank and moves the sprite
+ *   - Uses shadow_oam + oam_dma_flush so writes are clean
+ *
+ * Edit FROM this baseline rather than building from scratch — the
+ * boot order below is the GBC pitfall that costs new ports the most
+ * time (see TROUBLESHOOTING.md "screen is blank").
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+/* A simple 8×8 tile, 2bpp. Each row is 2 bytes; 8 rows × 2 = 16 bytes.
+ * Layout: row N's low-bits come from byte 2N, high-bits from byte 2N+1.
+ * This makes a hollow square (color 3 outline, color 0 fill). */
+static const uint8_t tile_data[16] = {
+  0xFF, 0xFF,   /* row 0: all color 3 */
+  0x81, 0x81,   /* row 1: outline only */
+  0x81, 0x81,
+  0x81, 0x81,
+  0x81, 0x81,
+  0x81, 0x81,
+  0x81, 0x81,
+  0xFF, 0xFF,   /* row 7: all color 3 */
+};
+
+/* CGB object palette 0 in BGR555. Color 0 must be transparent for sprites,
+ * but the value is still written (the hardware ignores it). */
+static const uint16_t obj_palette[4] = {
+  0x7FFF,  /* color 0 — transparent (any value) */
+  0x001F,  /* color 1 — red */
+  0x03E0,  /* color 2 — green */
+  0x7C00,  /* color 3 — blue */
+};
+
+/* CGB BG palette 0 — purple/violet so the backdrop is visibly NOT a
+ * DMG green tint. Confirms the CGB-mode header flip is working. */
+static const uint16_t bg_palette[4] = {
+  0x2010,  /* color 0 — dark purple backdrop */
+  0x3018,  /* color 1 */
+  0x4020,  /* color 2 */
+  0x6B5A,  /* color 3 — light highlight */
+};
+
+void main(void) {
+  uint8_t pad = 0;
+  uint8_t prev_pad = 0;
+  uint8_t x = 80;       /* hardware X = screen X + 8 */
+  uint8_t y = 80;       /* hardware Y = screen Y + 16 */
+  uint8_t i;
+
+  /* ── 1. LCD off (safe whether it was on or off) ──────────────────
+   * lcd_init_default() checks LCDC.7 and only waits for vblank if the
+   * LCD is on; otherwise LY is frozen at 0 and a blind wait would hang
+   * the entire boot. */
+  lcd_init_default();
+  LCDC = 0;             /* turn off again so we can write VRAM freely */
+
+  /* ── 2. Upload our tile to VRAM slot 1 ($8010) ───────────────────
+   * Slot 0 ($8000) is reserved for "blank" by convention so we don't
+   * accidentally render garbage tiles that point to it.
+   *
+   * Use memcpy_vram (bundled in gb_runtime.c) — a raw byte-copy loop
+   * into VRAM can be optimized away by SDCC and leave VRAM empty. See
+   * TROUBLESHOOTING.md "VRAM stays empty / sprite never appears". */
+  memcpy_vram((uint8_t *)0x8010, tile_data, 16);
+
+  /* ── 3. Object palette 0 (CGB path) ──────────────────────────────
+   * OCPS bit 7 = auto-increment after each write; bits 5..3 = palette
+   * index (0..7); bits 2..1 = color index (0..3); bit 0 = MSB select.
+   * Setting OCPS = 0x80 means "palette 0, color 0, low byte, then
+   * auto-advance". 8 byte writes = 4 colors × 2 bytes (BGR555).
+   *
+   * On DMG, OCPS/OCPD don't exist — the writes are silently dropped
+   * and DMG uses OBP0 instead, which lcd_init_default already set. */
+  OCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    OCPD = (uint8_t)(obj_palette[i] & 0xFF);        /* low byte */
+    OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF); /* high byte */
+  }
+
+  /* BG palette 0 — same auto-incrementing protocol on BCPS/BCPD. */
+  BCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    BCPD = (uint8_t)(bg_palette[i] & 0xFF);
+    BCPD = (uint8_t)((bg_palette[i] >> 8) & 0xFF);
+  }
+
+  /* ── 4. Build initial OAM ────────────────────────────────────────
+   * Clear all 40 slots, write our sprite into slot 0, then flush the
+   * shadow OAM to hardware BEFORE the LCD turns on — otherwise the very
+   * first displayed frame reads stale/zero OAM and the sprite is missing
+   * (or flat) for a frame. See TROUBLESHOOTING.md "first frame is blank". */
+  oam_clear();
+  oam_set(0, y, x, /* tile= */ 1, /* attr= */ 0);
+  oam_dma_flush();
+
+  /* ── 5. Turn the LCD back on with BG + OBJ enabled. ──────────────
+   * LCDC bits: 0x80=LCD on, 0x02=OBJ on, 0x10=tile data at $8000.
+   * (BG remains off — we have no BG map set up.) */
+  LCDC = LCDC_LCD_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+
+  /* ── 6. APU on — let the player beep ──────────────────────────── */
+  sound_init();
+
+  /* ── 7. Game loop ────────────────────────────────────────────────
+   * Order matters:
+   *   wait for vblank  → safe time to flush OAM
+   *   flush OAM        → push shadow_oam to hardware
+   *   read input       → for next frame's update
+   *   update           → mutate game state
+   * Then loop. */
+  for (;;) {
+    wait_vblank();
+    oam_dma_flush();
+    prev_pad = pad;
+    pad = joypad_read();
+
+    /* D-pad lives in the HIGH nybble of joypad_read's packed byte. */
+    if (pad & PAD_LEFT)  x--;
+    if (pad & PAD_RIGHT) x++;
+    if (pad & PAD_UP)    y--;
+    if (pad & PAD_DOWN)  y++;
+
+    /* Beep on the rising edge of A (one-shot, not held). */
+    if ((pad & PAD_A) && !(prev_pad & PAD_A)) {
+      /* C5-ish note on channel 2 (~261 Hz, ~120ms). */
+      sound_play_tone(2, 1798, 30);
+    }
+
+    /* Re-stage the sprite at its new position. */
+    oam_set(0, y, x, 1, 0);
+  }
+}

package/examples/gbc/templates/music_demo.c

@@ -0,0 +1,63 @@
+/* ── music_demo.c — hUGEDriver music player demo (GBC) ───────────────
+ *
+ * Plays the bundled sample_song (see song_data.c) on the GBC APU. The
+ * APU is identical between DMG and CGB modes, so the driver code is
+ * the same — only the BG-palette path differs (BCPS/BCPD instead of
+ * BGP). The .gbc extension flips $0143 = $80 → gambatte boots CGB mode.
+ *
+ * Driver: compact SDCC-native rewrite of the upstream hUGEDriver
+ * interface (https://github.com/SuperDisk/hUGEDriver, public domain).
+ *
+ * Wiring:
+ *   - sound_init()         power-on the APU
+ *   - hUGE_init(&song)     load song descriptor
+ *   - hUGE_dosound()       advance one tick; call once per vblank
+ *
+ * Visual: BG palette 0 cycles through 4 colors — purple/blue/green/red —
+ * via BCPS/BCPD writes, so the demo is unambiguously CGB-mode visible.
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+#include "hUGEDriver.h"
+
+extern const huge_song_t sample_song;
+
+static const uint16_t bg_colors[4] = {
+  0x4210,  /* dim purple */
+  0x4308,  /* dim blue   */
+  0x0252,  /* dim green  */
+  0x0017,  /* dim red    */
+};
+
+void main(void) {
+  uint8_t  i;
+  uint8_t  shade = 0;
+  uint16_t frame = 0;
+
+  lcd_init_default();
+  sound_init();
+
+  /* Write the initial CGB BG palette 0 (4 entries, same colour). */
+  BCPS = 0x80;            /* auto-increment, start at index 0 */
+  for (i = 0; i < 4; i++) {
+    BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
+    BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
+  }
+
+  hUGE_init(&sample_song);
+
+  for (;;) {
+    wait_vblank();
+    hUGE_dosound();
+    frame++;
+    if ((frame & 0x3F) == 0) {     /* every 64 frames ≈ 1 s */
+      shade = (uint8_t)((shade + 1) & 0x03);
+      BCPS = 0x80;
+      for (i = 0; i < 4; i++) {
+        BCPD = (uint8_t)(bg_colors[shade] & 0xFFu);
+        BCPD = (uint8_t)((bg_colors[shade] >> 8) & 0xFFu);
+      }
+    }
+  }
+}

package/examples/gbc/templates/platformer.c

@@ -0,0 +1,181 @@
+/* ── platformer.c — Game Boy Color SIDE-SCROLLING platformer scaffold ──
+ *
+ * A horizontally scrolling platformer: the world is 256 px wide (the
+ * full wrapping BG map), a camera follows the player and scrolls the BG
+ * via the SCX register. Gravity + jump + land-on-top collision against
+ * a static platform list in WORLD coords.
+ *
+ * Subpixel state (x/y in 1/16-pixel units) for fine acceleration. The
+ * player sprite draws at SCREEN x = (worldX>>4) - camX.
+ *
+ * Color: the BG and OBJ palettes are uploaded through the CGB palette
+ * registers (BCPS/BCPD and OCPS/OCPD) — full 15-bit color, unlike DMG.
+ *
+ * The world here is one BG map (256 px) so plain SCX scrolls it with no
+ * streaming. For a WIDER world, stream the next BG-map column each time
+ * camX crosses an 8-px boundary — see the GBC MENTAL_MODEL.md.
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+static const uint8_t tile_blank[16] = { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 };
+static const uint8_t tile_player[16] = {
+    0x18,0x18, 0x3C,0x3C, 0x7E,0x7E, 0xFF,0xFF,
+    0xFF,0xFF, 0x7E,0x7E, 0x3C,0x3C, 0x18,0x18,
+};
+static const uint8_t tile_platform[16] = {
+    0xFF,0xFF, 0x80,0x80, 0x80,0x80, 0x80,0x80,
+    0x80,0x80, 0x80,0x80, 0x80,0x80, 0xFF,0xFF,
+};
+
+static const uint16_t obj_palette[4] = { 0x7FFF, 0x001F, 0x03E0, 0x7C00 };
+static const uint16_t bg_palette[4]  = { 0x7FFF, 0x5294, 0x294A, 0x0000 };
+
+typedef struct { int16_t x, y, w, h; } Rect;
+
+#define WORLD_W  256
+#define SCREEN_W 160
+
+/* Platforms in WORLD coords, spread across the 256-px world. */
+static const Rect platforms[] = {
+    {   0, 128, 256,  16 }, /* floor spans the world */
+    {  16, 100,  40,   8 },
+    {  96,  96,  32,   8 },
+    { 168,  80,  40,   8 },
+    {  56,  64,  32,   8 },
+    { 200, 110,  40,   8 },
+    { 130,  48,  40,   8 },
+};
+#define N_PLATFORMS (sizeof(platforms)/sizeof(platforms[0]))
+
+static uint8_t on_platform(int16_t px, int16_t py) {
+    uint8_t i;
+    const Rect *p;
+    for (i = 0; i < N_PLATFORMS; i++) {
+        p = &platforms[i];
+        if (py + 8 == p->y && px + 8 > p->x && px < p->x + p->w) return 1;
+    }
+    return 0;
+}
+
+static void upload_tile(uint8_t slot, const uint8_t *src) {
+    uint8_t *dst = (uint8_t *)(0x8000 + slot * 16);
+    uint8_t i;
+    for (i = 0; i < 16; i++) dst[i] = src[i];
+}
+
+static void paint_platforms(void) {
+    /* Each cell of the BG map is 8×8, BG map base $9800. */
+    uint8_t *map = (uint8_t *)0x9800;
+    uint8_t i, j;
+    uint16_t k;
+    int16_t cx, cy, cw, ch;
+    const Rect *p;
+    /* k MUST be uint16_t: 32*18 = 576 > 255, so a uint8_t counter would
+     * never reach the bound and this loop would spin forever (the BG map
+     * never clears, main() never starts). Classic SDCC limited-range trap. */
+    for (k = 0; k < 32 * 18; k++) map[k] = 0; /* blank tile slot 0 */
+    for (i = 0; i < N_PLATFORMS; i++) {
+        p = &platforms[i];
+        cx = p->x >> 3;
+        cy = p->y >> 3;
+        cw = (p->w + 7) >> 3;
+        ch = (p->h + 7) >> 3;
+        for (j = 0; j < cw; j++) {
+            if (cx + j < 32 && cy < 32)
+                map[cy * 32 + cx + j] = 2; /* tile slot 2 = platform */
+        }
+    }
+}
+
+void main(void) {
+    int16_t px = 16 << 4, py = 60 << 4;
+    int16_t vx = 0,       vy = 0;
+    int16_t ipx, ipy, npy, camX = 0;
+    int32_t np;
+    uint8_t grounded;
+    uint8_t pad, prev = 0, i;
+    const Rect *p;
+    const int16_t GRAVITY = 10;
+    const int16_t MOVE    = 20;
+    const int16_t JUMP    = -180;
+    const int16_t MAXFALL = 280;
+
+    lcd_init_default();
+    enable_vblank_irq();   /* MANDATORY: HALT-driven wait_vblank. Without this,
+                            * busy-poll wait_vblank runs ~1/30 speed on the WASM
+                            * emulator and the game loop appears to hang. */
+    LCDC = 0;
+
+    upload_tile(0, tile_blank);
+    upload_tile(1, tile_player);
+    upload_tile(2, tile_platform);
+
+    OCPS = 0x80;
+    for (i = 0; i < 4; i++) {
+        OCPD = (uint8_t)(obj_palette[i] & 0xFF);
+        OCPD = (uint8_t)((obj_palette[i] >> 8) & 0xFF);
+    }
+    BCPS = 0x80;
+    for (i = 0; i < 4; i++) {
+        BCPD = (uint8_t)(bg_palette[i] & 0xFF);
+        BCPD = (uint8_t)((bg_palette[i] >> 8) & 0xFF);
+    }
+
+    paint_platforms();
+    oam_clear();
+    LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+
+    while (1) {
+        wait_vblank();
+
+        ipx = px >> 4;
+        ipy = py >> 4;
+
+        /* Camera follows the player, centered, clamped to the world.
+         * Write SCX so the BG scrolls; player is drawn in SCREEN space. */
+        camX = ipx - (SCREEN_W / 2 - 4);
+        if (camX < 0) camX = 0;
+        if (camX > WORLD_W - SCREEN_W) camX = WORLD_W - SCREEN_W;
+        SCX = (uint8_t)camX;
+
+        for (i = 0; i < 40; i++) oam_set(i, 0, 0, 0, 0);
+        oam_set(0, ipy + 16, (ipx - camX) + 8, 1, 0);  /* screen x = world - cam */
+        oam_dma_flush();
+
+        pad = joypad_read();
+        vx = 0;
+        if (pad & PAD_LEFT)  vx = -MOVE;
+        if (pad & PAD_RIGHT) vx =  MOVE;
+
+        grounded = on_platform(ipx, ipy);
+        if ((pad & PAD_A) && !(prev & PAD_A) && grounded) vy = JUMP;
+        prev = pad;
+
+        vy += GRAVITY;
+        if (vy > MAXFALL) vy = MAXFALL;
+        if (grounded && vy > 0) vy = 0;
+
+        px += vx;
+        if (px < 0) px = 0;
+        if (px > (WORLD_W - 8) << 4) px = (WORLD_W - 8) << 4;
+
+        np = py + vy;
+        npy = np >> 4;
+        if (vy > 0) {
+            for (i = 0; i < N_PLATFORMS; i++) {
+                p = &platforms[i];
+                if (ipy + 8 <= p->y && npy + 8 >= p->y
+                    && ipx + 8 > p->x && ipx < p->x + p->w) {
+                    py = (p->y - 8) << 4;
+                    vy = 0;
+                    goto done;
+                }
+            }
+        }
+        py = np;
+        if (py > 144 << 4) { py = 0; vy = 0; }
+done:   ;
+    }
+}