romdev-mcp 0.1.1

package/examples/gbc/templates/tile_engine.c

@@ -0,0 +1,280 @@
+/* ── tile_engine.c — GBC starter with a tile map + multiple rooms ──
+ *
+ * Single-screen-per-room layout (Adventure / Zelda-1 / Sokoban shape).
+ *   - 20×18 BG map rendered from a `room[]` array
+ *   - Walk a sprite around with the d-pad
+ *   - Crossing the screen edge transitions to the next room
+ *   - 3 hand-written rooms wired up; extend with more for a real game
+ *
+ * Boot order follows the GBC "must-do" sequence from
+ * src/platforms/gbc/TROUBLESHOOTING.md — do not reorder.
+ *
+ * Tile data layout (8×8, 2bpp, 16 bytes per tile):
+ *   tile 0 — blank          (always reserved so OAM Y=0 doesn't glitch)
+ *   tile 1 — floor          (light)
+ *   tile 2 — wall            (dark, solid outline)
+ *   tile 3 — door             (different color)
+ *   tile 4 — player sprite
+ */
+
+#include "gb_hardware.h"
+#include "gb_runtime.h"
+
+/* ── Tile data ──────────────────────────────────────────────────── */
+/* Each tile is 16 bytes: 8 rows × 2 bytes/row.
+ * For row N, byte 2N has the LOW colour bits, byte 2N+1 has the HIGH.
+ *   colour 0 = 0 bit lo, 0 bit hi  (transparent on sprites)
+ *   colour 1 = 1 bit lo, 0 bit hi
+ *   colour 2 = 0 bit lo, 1 bit hi
+ *   colour 3 = 1 bit lo, 1 bit hi
+ */
+static const uint8_t tiles[5 * 16] = {
+  /* tile 0: blank (all colour 0) */
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+
+  /* tile 1: floor (all colour 1) */
+  0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00,
+  0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00,
+
+  /* tile 2: wall (all colour 3) */
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+
+  /* tile 3: door (colour 2 outline, colour 1 fill) */
+  0xFF, 0xFF, 0x81, 0xFF, 0x81, 0xFF, 0x81, 0xFF,
+  0x81, 0xFF, 0x81, 0xFF, 0x81, 0xFF, 0xFF, 0xFF,
+
+  /* tile 4: player sprite (colour 3 outline, colour 0 fill) */
+  0x3C, 0x3C, 0x42, 0x42, 0x81, 0x81, 0x81, 0x81,
+  0x81, 0x81, 0x81, 0x81, 0x42, 0x42, 0x3C, 0x3C,
+};
+
+/* ── Palettes (BGR555) ──────────────────────────────────────────── */
+/* CGB palette layout: 8 BG palettes × 4 colours × 2 bytes = 64 bytes.
+ * BCPS bit 7 = auto-increment; bits 5..3 = palette; bits 2..1 = colour;
+ * bit 0 = byte select (lo/hi). 0x80 = "palette 0, colour 0, byte 0, auto-increment". */
+static const uint16_t bg_pal[4] = {
+  0x7FFF,  /* 0: white */
+  0x3DEF,  /* 1: pale yellow (floor) */
+  0x4210,  /* 2: dark grey (door outline) */
+  0x0C63,  /* 3: dark grey (wall) */
+};
+
+/* Sprite palette — single 4-colour palette in OBJ palette 0. */
+static const uint16_t obj_pal[4] = {
+  0x7FFF,  /* 0: transparent */
+  0x001F,  /* 1: red */
+  0x03E0,  /* 2: green */
+  0x7C00,  /* 3: blue (player outline) */
+};
+
+/* ── Rooms ──────────────────────────────────────────────────────── */
+/* 20 columns × 18 rows. Tile index per cell.
+ * Edges are walls (tile 2). One door per side leads to the next room. */
+#define COLS 20
+#define ROWS 18
+#define ROOMS 3
+
+static const uint8_t rooms[ROOMS][ROWS * COLS] = {
+  /* Room 0: a corridor — door on right */
+  {
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+  },
+  /* Room 1: open hall — doors left and right */
+  {
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,3,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,2,2,2,2,2,2,2,2,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+  },
+  /* Room 2: end room — door on left only */
+  {
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,2,2,2,2,2,1,1,1,1,2,2,2,2,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,2,1,2,2,1,1,1,1,2,2,1,2,2,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    3,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,2,2,1,2,2,1,1,1,1,2,2,1,2,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,1,1,1,2,1,1,1,1,2,1,1,1,2,1,1,2,
+    2,1,1,2,2,2,2,2,1,1,1,1,2,2,2,2,2,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,2,
+    2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,2,
+  },
+};
+
+/* ── Helpers ────────────────────────────────────────────────────── */
+static void copy_to_vram(uint8_t *dst, const uint8_t *src, uint16_t n) {
+  uint16_t i;
+  for (i = 0; i < n; i++) dst[i] = src[i];
+}
+
+static void load_bg_palette(void) {
+  uint8_t i;
+  BCPS = 0x80;  /* palette 0, colour 0, lo byte, auto-increment */
+  for (i = 0; i < 4; i++) {
+    BCPD = (uint8_t)(bg_pal[i] & 0xFF);
+    BCPD = (uint8_t)((bg_pal[i] >> 8) & 0xFF);
+  }
+}
+
+static void load_obj_palette(void) {
+  uint8_t i;
+  OCPS = 0x80;
+  for (i = 0; i < 4; i++) {
+    OCPD = (uint8_t)(obj_pal[i] & 0xFF);
+    OCPD = (uint8_t)((obj_pal[i] >> 8) & 0xFF);
+  }
+}
+
+static void render_room(uint8_t room_idx) {
+  /* Write the 20×18 map into BG map 1 at $9800. The hardware BG map is
+   * 32 tiles wide, so each game row spans 32 bytes in VRAM but we only
+   * use the first 20. */
+  uint16_t i, j;
+  uint8_t *bg_map = (uint8_t *)0x9800;
+  const uint8_t *room = rooms[room_idx];
+  for (j = 0; j < ROWS; j++) {
+    for (i = 0; i < COLS; i++) {
+      bg_map[j * 32 + i] = room[j * COLS + i];
+    }
+  }
+}
+
+/* Returns true if the tile at (tx, ty) in the current room is solid. */
+static uint8_t solid(uint8_t room_idx, uint8_t tx, uint8_t ty) {
+  uint8_t t;
+  if (tx >= COLS || ty >= ROWS) return 1;
+  t = rooms[room_idx][ty * COLS + tx];
+  return (t == 2);  /* tile 2 = wall */
+}
+
+/* Returns true if the tile at (tx, ty) is a door. */
+static uint8_t is_door(uint8_t room_idx, uint8_t tx, uint8_t ty) {
+  uint8_t t;
+  if (tx >= COLS || ty >= ROWS) return 0;
+  t = rooms[room_idx][ty * COLS + tx];
+  return (t == 3);
+}
+
+void main(void) {
+  uint8_t px = 80;        /* player screen X (hardware = +8) */
+  uint8_t py = 72;        /* player screen Y (hardware = +16) */
+  uint8_t current_room = 0;
+  uint8_t pad;
+  uint8_t nx, ny;
+  uint8_t tx, ty;
+
+  /* ── 1. LCD off, safely ────────────────────────────────────────── */
+  lcd_init_default();
+  LCDC = 0;
+
+  /* ── 2. Upload tile data to VRAM slot 0 ($8000) ────────────────── */
+  copy_to_vram((uint8_t *)0x8000, tiles, sizeof(tiles));
+
+  /* ── 3. Palettes ───────────────────────────────────────────────── */
+  load_bg_palette();
+  load_obj_palette();
+
+  /* ── 4. Render starting room ───────────────────────────────────── */
+  render_room(current_room);
+
+  /* ── 5. Build initial OAM ──────────────────────────────────────── */
+  oam_clear();
+  oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+
+  /* ── 6. LCD back on with BG + OBJ ──────────────────────────────── */
+  LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+
+  /* ── 7. Game loop ──────────────────────────────────────────────── */
+  for (;;) {
+    wait_vblank();
+    oam_dma_flush();
+    pad = joypad_read();
+
+    /* Tentative new position. */
+    nx = px;
+    ny = py;
+    if (pad & PAD_LEFT)  nx--;
+    if (pad & PAD_RIGHT) nx++;
+    if (pad & PAD_UP)    ny--;
+    if (pad & PAD_DOWN)  ny++;
+
+    /* Tile under the player's centre (player is 8×8). */
+    tx = (uint8_t)(nx >> 3);
+    ty = (uint8_t)(ny >> 3);
+
+    /* Door — transition to neighbouring room. */
+    if (is_door(current_room, tx, ty)) {
+      if (nx >= 152) {        /* right edge → next room */
+        if (current_room < ROOMS - 1) {
+          current_room++;
+          px = 4;             /* enter at left side */
+          py = ny;
+          LCDC = 0;
+          render_room(current_room);
+          LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+          oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+          continue;
+        }
+      } else if (nx <= 4) {   /* left edge → previous room */
+        if (current_room > 0) {
+          current_room--;
+          px = 148;            /* enter at right side */
+          py = ny;
+          LCDC = 0;
+          render_room(current_room);
+          LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO;
+          oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+          continue;
+        }
+      }
+    }
+
+    /* Wall collision — block movement. */
+    if (!solid(current_room, tx, ty)) {
+      px = nx;
+      py = ny;
+    }
+
+    oam_set(0, (uint8_t)(py + 16), (uint8_t)(px + 8), 4, 0);
+  }
+}

package/examples/genesis/main.s

@@ -0,0 +1,161 @@
+; Hello, Genesis — a real hello-world scaffold for vasm68k_mot.
+;
+; What this does:
+;   1. Vector table (SP + reset, rest stubs).
+;   2. ROM header at $100 (256 bytes — gpgx auto-skips this if minimal).
+;   3. Init: program VDP registers for 320x224 H40 mode, sane defaults.
+;   4. Upload a 4-color palette to CRAM.
+;   5. Write one 4bpp tile (a yellow 'H') into VRAM at tile $0001.
+;   6. Place that tile near screen center in plane A.
+;   7. Enable display and park forever.
+;
+; BUILD:
+;   buildSource({ platform: "genesis", source: /* this file */ });
+;
+; vasm syntax gotchas (in case you go beyond this scaffold):
+;   - NO space after commas in operands: `move.w #$2700, sr` FAILS.
+;     Write `move.w #$2700,sr` instead.
+;   - WRAM at $FF0000-$FFFFFF: use `equ` for variable addresses, not
+;     `org $00FF0000` (that produces a 16MB ROM).
+;   - VDP control reg ($C00004) takes 16-bit writes; VDP data ($C00000)
+;     also 16-bit. Always pair high+low.
+;
+; See getStarterSnippet({platform:"genesis", name:"..."}) for richer
+; building blocks (vdp_init, vblank_wait, pad_read, sprite_table, etc.)
+; and src/platforms/genesis/lib/README.md for the full quickstart.
+
+; -----------------------------------------------------------------------
+; Memory map — VDP ports.
+VDP_DATA    equ $C00000     ; word-write data port
+VDP_CTRL    equ $C00004     ; word-write control port (also reads status)
+
+; CRAM (color) word offsets: each entry is BGR-555 in low 12 bits.
+; Format constants below build VRAM/CRAM/VSRAM write commands.
+
+; -----------------------------------------------------------------------
+; Vector table at $000000.
+        org     $000000
+        dc.l    $00FFE000          ; initial stack pointer
+        dc.l    Start              ; reset vector
+        dcb.l   62,Exception       ; rest of vectors → exception stub
+
+; -----------------------------------------------------------------------
+; ROM header at $000100 (256 bytes). Many of these fields don't matter
+; for emulators; gpgx accepts mostly-empty headers fine.
+        org     $000100
+        dc.b    'SEGA GENESIS    '              ; console name (16 bytes)
+        dc.b    '(C)ROMDEV 2026.MAY'            ; copyright (16 bytes)
+        dc.b    'HELLO WORLD                                     '  ; domestic name (48)
+        dc.b    'HELLO WORLD                                     '  ; intl name (48)
+        dc.b    'GM 00000000-00'                ; serial (14)
+        dc.w    $0000                           ; checksum
+        dc.b    'J               '              ; I/O support (16)
+        dc.l    $00000000                       ; ROM start
+        dc.l    $000FFFFF                       ; ROM end (1MB cap)
+        dc.l    $00FF0000                       ; RAM start
+        dc.l    $00FFFFFF                       ; RAM end
+        dc.b    '            '                  ; SRAM info (12)
+        dc.b    '                                        '  ; notes (40)
+        dc.b    'JUE             '              ; region (16)
+
+; -----------------------------------------------------------------------
+; Exception handler — minimal, just spin.
+        org     $000200
+Exception:
+        bra     Exception
+
+; -----------------------------------------------------------------------
+; Reset entry point.
+Start:
+        move.w  #$2700,sr               ; disable interrupts (NO space after comma!)
+
+        ; Wait a few cycles for the Z80 to settle.
+        ; (Real code grants Z80 bus and resets it — omitted here for brevity.)
+
+        ; -----------------------------------------------------------
+        ; Program VDP registers for 320x224 H40 mode. Register-write
+        ; format: $8000 | (reg << 8) | value, written to VDP_CTRL.
+        lea     VDP_CTRL,a0
+        lea     VDPRegs(pc),a1
+        moveq   #18-1,d0             ; 18 register writes
+.vdp_loop:
+        move.w  (a1)+,(a0)
+        dbra    d0,.vdp_loop
+
+        ; -----------------------------------------------------------
+        ; Upload palette 0 to CRAM (4 colors).
+        ; CRAM write command: $C0000003 (addr 0, code 3 = CRAM write).
+        move.l  #$C0000000,VDP_CTRL
+        move.w  #$0000,VDP_DATA      ; color 0: transparent / backdrop
+        move.w  #$0EEE,VDP_DATA      ; color 1: white-ish ($0E in each nybble)
+        move.w  #$00EE,VDP_DATA      ; color 2: yellow
+        move.w  #$0E00,VDP_DATA      ; color 3: blue (unused)
+
+        ; -----------------------------------------------------------
+        ; Upload one 4bpp tile (8x8 'H', color 2 = yellow) to VRAM at
+        ; tile #1 (byte offset $20). Tile data is 32 bytes (8 rows × 4
+        ; bytes/row at 4bpp). Each byte = 2 pixels (high nybble = left).
+        ;
+        ; VRAM write command for byte $0020 = $40200000.
+        move.l  #$40200000,VDP_CTRL
+        lea     TileH(pc),a1
+        moveq   #8-1,d0              ; 8 rows
+.tile_loop:
+        move.l  (a1)+,VDP_DATA       ; each row = one longword (4 bytes)
+        dbra    d0,.tile_loop
+
+        ; -----------------------------------------------------------
+        ; Place tile #1 in plane A near screen center.
+        ; Plane A base is at VRAM $C000 (default after VDP init).
+        ; Cell (col, row) = (20, 14). Plane A is 64 cells wide here, so
+        ; byte offset = ((14*64) + 20) * 2 = 1832 = $728.
+        ; VRAM write to plane A cell: $C000 + $728 = $C728.
+        ; VDP cmd for VRAM write at $C728 = $40080003 = ... compute:
+        ;   addr lo = $C728 & $3FFF = $0728
+        ;   addr hi = ($C728 >> 14) | code(VRAM_W=$01) = $03 | $01 = $03
+        ; → $40280003
+        move.l  #$40280003,VDP_CTRL
+        move.w  #$0001,VDP_DATA      ; tile #1, palette 0, no flip, low pri
+
+        ; -----------------------------------------------------------
+        ; Enable display (VDP reg 1, bit 6).
+        move.w  #$8174,VDP_CTRL      ; reg 1 = $74 (display on + V28 + DMA en)
+
+Forever:
+        bra     Forever
+
+; -----------------------------------------------------------------------
+; VDP register init values. 18 registers programmed at boot.
+VDPRegs:
+        dc.w    $8004    ; reg 0:  no HInt, palette, disable display
+        dc.w    $8134    ; reg 1:  display OFF for now (we re-enable later)
+        dc.w    $8230    ; reg 2:  plane A name table at $C000
+        dc.w    $8300    ; reg 3:  window name table at $0000 (unused)
+        dc.w    $8407    ; reg 4:  plane B name table at $E000
+        dc.w    $855C    ; reg 5:  sprite table at $B800
+        dc.w    $8600    ; reg 6:  unused
+        dc.w    $8700    ; reg 7:  backdrop color = palette 0, color 0
+        dc.w    $8800    ; reg 8/9: unused
+        dc.w    $8900
+        dc.w    $8AFF    ; reg 10: HInterrupt counter (max)
+        dc.w    $8B00    ; reg 11: no full-screen scroll
+        dc.w    $8C81    ; reg 12: H40 mode (320 wide)
+        dc.w    $8D2F    ; reg 13: HScroll table at $B400
+        dc.w    $8E00    ; reg 14: unused
+        dc.w    $8F02    ; reg 15: auto-increment +2
+        dc.w    $9001    ; reg 16: plane size = 64x32 (H64 V32)
+        dc.w    $9100    ; reg 17: window x off
+        dc.w    $9200    ; (extra) window y off — included for safety
+
+; -----------------------------------------------------------------------
+; 4bpp tile data for 'H' — color index 2 (yellow) where bit set.
+; 8 rows × 4 bytes/row. High nybble of each byte = left pixel.
+TileH:
+        dc.l    $20000020       ; row 0: 2.....2  → 0010 0000 0000 0000 0000 0000 0010 0000
+        dc.l    $20000020
+        dc.l    $20000020
+        dc.l    $22222220       ; row 3: 2222222.
+        dc.l    $20000020
+        dc.l    $20000020
+        dc.l    $20000020
+        dc.l    $00000000       ; row 7: blank

package/examples/genesis/templates/hello_sprite.c

@@ -0,0 +1,75 @@
+/* ── hello_sprite.c — Genesis SGDK starter (one sprite + d-pad) ───
+ *
+ * Drives one sprite around the screen with the directional pad. Uses
+ * SGDK's lightweight VDP_setSprite() path (NOT the higher-level
+ * sprite engine — that's reserved for hello_sprite + the genre
+ * scaffolds where animation frames matter).
+ *
+ * Boots-from-cold game-loop shape:
+ *   1. main(bool hard) — SGDK already initialised VDP + default
+ *      palette in sega.s before us. We just load a tile + start drawing.
+ *   2. Upload one 8×8 tile (filled square) to VRAM at TILE_USER_INDEX.
+ *   3. Set sprite palette entry 1 to white so the tile shows up.
+ *   4. Game loop: poll JOY_1, move sprite, VDP_setSprite + flush via
+ *      VDP_updateSprites, then SYS_doVBlankProcess() to sync to vblank.
+ *
+ * Why VDP_updateSprites every frame?
+ *   The VDP keeps its sprite-attribute table (SAT) in VRAM. SGDK
+ *   buffers updates in vdpSpriteCache RAM-side and flushes via DMA
+ *   on demand. Forget the flush → sprite never appears.
+ */
+
+#include <genesis.h>
+
+/* A simple 8×8 tile, 4bpp Genesis format (32 bytes = 8 rows × 4 bytes
+ * each, each byte = two 4-bit pixels). All pixels are colour index 1,
+ * which we set to white below. */
+static const u32 tile_data[8] = {
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+    0x11111111, 0x11111111, 0x11111111, 0x11111111,
+};
+
+int main(bool hard) {
+    (void)hard;
+
+    s16 px = 152;  /* roughly mid-screen X (320 = H40, 152 ≈ centre - 8) */
+    s16 py = 108;  /* roughly mid-screen Y (224 visible lines) */
+    u16 prev = 0;
+
+    /* Make sure sprite palette 0 entry 1 is white so we can see our
+     * tile. SGDK uses 0RRR0GGG0BBB packed words (BGR, 3 bits each). */
+    PAL_setColor(1, 0x0EEE); /* near-white */
+
+    /* Upload the user tile to VRAM at TILE_USER_INDEX (everything
+     * below that is reserved for SGDK's font + system tiles). */
+    VDP_loadTileData(tile_data, TILE_USER_INDEX, 1, DMA);
+
+    VDP_drawText("D-PAD MOVES THE SPRITE", 8, 2);
+    VDP_drawText("START FOR SOFT RESET",  9, 4);
+
+    while (TRUE) {
+        u16 pad = JOY_readJoypad(JOY_1);
+
+        if (pad & BUTTON_LEFT)  px -= 2;
+        if (pad & BUTTON_RIGHT) px += 2;
+        if (pad & BUTTON_UP)    py -= 2;
+        if (pad & BUTTON_DOWN)  py += 2;
+
+        /* Edge-detected START → soft-reset back to centre. */
+        if ((pad & BUTTON_START) && !(prev & BUTTON_START)) {
+            px = 152;
+            py = 108;
+        }
+        prev = pad;
+
+        /* Stage the sprite, flush the SAT, then sync to vblank.
+         * SPRITE_SIZE(1,1) = 8×8. TILE_ATTR_FULL(palette,prio,vflip,
+         * hflip,tile_index). */
+        VDP_setSprite(0, px, py, SPRITE_SIZE(1, 1),
+                      TILE_ATTR_FULL(PAL0, 0, 0, 0, TILE_USER_INDEX));
+        VDP_updateSprites(1, DMA);
+
+        SYS_doVBlankProcess();
+    }
+    return 0;
+}

package/examples/genesis/templates/platformer.c

@@ -0,0 +1,166 @@
+/* ── platformer.c — Genesis SGDK side-scrolling platformer scaffold ─
+ *
+ * A HORIZONTALLY SCROLLING platformer: the world is wider than the
+ * screen, a camera follows the player, Plane A scrolls with the world
+ * and Plane B scrolls at half rate for parallax depth. Gravity, jump,
+ * and land-on-top collision against a static platform list (in WORLD
+ * coords). Yours to extend with enemies, goals, pickups, etc.
+ *
+ * Physics is fixed-point: x/y are in 1/16-pixel subpixel units. The
+ * player draws at SCREEN x = (worldX>>4) - camX.
+ *
+ * World width here is one VDP plane (64 cells = 512 px) so the whole
+ * level fits in the scroll plane and plain VDP_setHorizontalScroll moves
+ * it — a real working scroller with no streaming. For a world WIDER than
+ * 512 px you additionally stream the column entering view each time camX
+ * crosses an 8-px boundary (see MENTAL_MODEL.md "Horizontal scrolling").
+ */
+
+#include <genesis.h>
+#include "genesis_sfx.h"
+
+#define T_BLANK    (TILE_USER_INDEX + 0)
+#define T_PLATFORM (TILE_USER_INDEX + 1)
+#define T_PLAYER   (TILE_USER_INDEX + 2)
+#define T_BG       (TILE_USER_INDEX + 3)
+
+static const u32 tile_blank[8]    = { 0,0,0,0,0,0,0,0 };
+static const u32 tile_platform[8] = {
+    0x11111111, 0x12222221, 0x12222221, 0x12222221,
+    0x12222221, 0x12222221, 0x12222221, 0x11111111,
+};
+static const u32 tile_player[8]   = {
+    0x00033000, 0x00333300, 0x03333330, 0x03333330,
+    0x03333330, 0x03333330, 0x00333300, 0x00033000,
+};
+/* A simple background block for the parallax plane. */
+static const u32 tile_bg[8] = {
+    0x44444444, 0x40000004, 0x40000004, 0x40000004,
+    0x40000004, 0x40000004, 0x40000004, 0x44444444,
+};
+
+#define WORLD_W   512          /* one 64-cell plane wide */
+#define SCREEN_W  320
+
+typedef struct { s16 x, y, w, h; } Rect;
+
+/* Static platforms in WORLD PIXEL coords (not subpixel), spread across
+ * the full 512-px world so there's somewhere to scroll to. */
+static const Rect platforms[] = {
+    {   0, 200, 512,  24 }, /* floor spans the whole world */
+    {  40, 160,  64,   8 },
+    { 150, 140,  72,   8 },
+    { 260, 120,  56,   8 },
+    { 360,  96,  64,   8 },
+    { 440, 150,  56,   8 },
+    { 200,  80,  48,   8 },
+};
+#define N_PLATFORMS (sizeof(platforms) / sizeof(platforms[0]))
+
+static bool on_platform(s16 px, s16 py) {
+    for (u16 i = 0; i < N_PLATFORMS; i++) {
+        const Rect* p = &platforms[i];
+        if (py + 8 == p->y && px + 8 > p->x && px < p->x + p->w) return TRUE;
+    }
+    return FALSE;
+}
+
+int main(bool hard) {
+    (void)hard;
+
+    PAL_setColor(0 + 2, 0x000E); /* player red  */
+    PAL_setColor(0 + 3, 0x00CC);
+    PAL_setColor(16 + 1, 0x0888); /* platform light */
+    PAL_setColor(16 + 2, 0x0666); /* platform dark  */
+    PAL_setColor(16 + 4, 0x0420); /* parallax bg    */
+
+    VDP_loadTileData(tile_blank,    T_BLANK,    1, DMA);
+    VDP_loadTileData(tile_platform, T_PLATFORM, 1, DMA);
+    VDP_loadTileData(tile_player,   T_PLAYER,   1, DMA);
+    VDP_loadTileData(tile_bg,       T_BG,       1, DMA);
+
+    /* Plane A: the foreground world — platforms painted in world coords. */
+    for (u16 i = 0; i < N_PLATFORMS; i++) {
+        const Rect* p = &platforms[i];
+        VDP_fillTileMapRect(BG_A,
+            TILE_ATTR_FULL(PAL1, 0, 0, 0, T_PLATFORM),
+            p->x >> 3, p->y >> 3, (p->w + 7) >> 3, (p->h + 7) >> 3);
+    }
+    /* Plane B: a sparse parallax backdrop — every 4th cell, upper area. */
+    for (u16 cx = 0; cx < 64; cx += 4)
+        for (u16 cy = 2; cy < 20; cy += 4)
+            VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL1, 0, 0, 0, T_BG), cx, cy);
+
+    VDP_drawText("D-PAD MOVE  A JUMP  (scrolls)", 5, 1);
+
+    sfx_init();
+
+    s32 px = 32 << 4, py = 100 << 4;   /* world subpixel coords */
+    s32 vx = 0, vy = 0;
+    s16 camX = 0;
+
+    const s32 GRAVITY = 12, MOVE_SPEED = 24, JUMP_VEL = -200, MAX_FALL = 320;
+    u16 prev = 0;
+
+    while (TRUE) {
+        u16 pad = JOY_readJoypad(JOY_1);
+
+        vx = 0;
+        if (pad & BUTTON_LEFT)  vx = -MOVE_SPEED;
+        if (pad & BUTTON_RIGHT) vx =  MOVE_SPEED;
+
+        s16 ipx = px >> 4, ipy = py >> 4;
+        bool grounded = on_platform(ipx, ipy);
+        if ((pad & BUTTON_A) && !(prev & BUTTON_A) && grounded) {
+            vy = JUMP_VEL; sfx_tone(1, 300, 6);
+        }
+        prev = pad;
+
+        vy += GRAVITY;
+        if (vy > MAX_FALL) vy = MAX_FALL;
+        if (grounded && vy > 0) vy = 0;
+
+        /* Horizontal move, clamped to the world (no wrap now — it scrolls). */
+        px += vx;
+        if (px < 0) px = 0;
+        if (px > (WORLD_W - 8) << 4) px = (WORLD_W - 8) << 4;
+
+        /* Vertical move with land-on-top snap. */
+        s32 np = py + vy; s16 npy = np >> 4;
+        bool landed = FALSE;
+        if (vy > 0) {
+            for (u16 i = 0; i < N_PLATFORMS; i++) {
+                const Rect* 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; landed = TRUE;
+                    sfx_tone(2, 700, 3); break;
+                }
+            }
+        }
+        if (!landed) {
+            py = np;
+            if (py > 224 << 4) { py = 0; vy = 0; }
+        }
+
+        /* Camera follows the player, centered, clamped to the world. */
+        camX = (px >> 4) - (SCREEN_W / 2 - 4);
+        if (camX < 0) camX = 0;
+        if (camX > WORLD_W - SCREEN_W) camX = WORLD_W - SCREEN_W;
+
+        /* Scroll: Plane A with the world, Plane B at half rate (parallax).
+         * The VDP scroll value moves the plane LEFT for positive camX, so
+         * we write the negative camera offset. */
+        VDP_setHorizontalScroll(BG_A, -camX);
+        VDP_setHorizontalScroll(BG_B, -(camX >> 1));
+
+        /* Player drawn in SCREEN space = world - camera. */
+        VDP_setSprite(0, (px >> 4) - camX, py >> 4, SPRITE_SIZE(1, 1),
+                      TILE_ATTR_FULL(PAL0, 1, 0, 0, T_PLAYER));
+        VDP_updateSprites(1, DMA);
+
+        sfx_update();
+        SYS_doVBlankProcess();
+    }
+    return 0;
+}