romdevtools 0.15.0 → 0.21.0

package/examples/nes/templates/puzzle.c

@@ -53,12 +53,39 @@ static const uint8_t tile_block_b[16] = {
   0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
   0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
 };
+/* BG scenery tiles — painted into the nametable so the playfield reads as a
+ * real machine on boot (without them the screen is just sprites on flat
+ * black). All live in the BACKGROUND pattern table ($1000); the block tiles
+ * above are sprites ($0000).
+ *
+ *   BG_WALL  — solid bordered block (idx 1, steel blue): the well frame.
+ *   BG_BRICK — a brick/dither pattern (idx 2) tiling the cabinet wall that
+ *              surrounds the well, so the whole screen is covered.
+ *   BG_INNER — a faint grid speck (idx 3) lining the inside of the well so
+ *              empty cells read as a recessed playfield, not a black hole. */
+static const uint8_t tile_wall[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_brick[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear */
+  0xFF, 0x80, 0x80, 0x80, 0xFF, 0x08, 0x08, 0x08,   /* plane 1 → colour 2 brick */
+};
+static const uint8_t tile_inner[16] = {
+  0x88, 0x00, 0x00, 0x00, 0x88, 0x00, 0x00, 0x00,   /* plane 0 specks */
+  0x88, 0x00, 0x00, 0x00, 0x88, 0x00, 0x00, 0x00,   /* plane 1 too → colour 3 */
+};
+#define BG_WALL  1   /* BG tile index 1 → uploaded to $1010 */
+#define BG_BRICK 2   /* BG tile index 2 → uploaded to $1020 */
+#define BG_INNER 3   /* BG tile index 3 → uploaded to $1030 */
 
 static const uint8_t palette[32] = {
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
-  0x0F, 0x10, 0x20, 0x30,
+  /* BG0: backdrop near-black, wall = steel blue (idx1), brick = brown
+   * (idx2), inner grid = dark grey (idx3). */
+  0x0F, 0x11, 0x17, 0x00,
+  0x0F, 0x11, 0x17, 0x00,
+  0x0F, 0x11, 0x17, 0x00,
+  0x0F, 0x11, 0x17, 0x00,
   /* Sprite palette 0: idx1=red, idx2=green, idx3=blue */
   0x0F, 0x16, 0x1A, 0x12,
   0x0F, 0x16, 0x1A, 0x12,
@@ -156,11 +183,45 @@ void main(void) {
   int8_t  i;
 
   ppu_off();
-  chr_ram_upload(0x0000, tile_blank,    16);
-  chr_ram_upload(0x0010, tile_block_r,  16);
+  chr_ram_upload(0x0000, tile_blank,    16);  /* sprite slot 0 */
+  chr_ram_upload(0x0010, tile_block_r,  16);  /* sprite slots 1..3 */
   chr_ram_upload(0x0020, tile_block_g,  16);
   chr_ram_upload(0x0030, tile_block_b,  16);
+  chr_ram_upload(0x1010, tile_wall,     16);  /* BG slot 1 (background table) */
+  chr_ram_upload(0x1020, tile_brick,    16);  /* BG slot 2 (cabinet wall)     */
+  chr_ram_upload(0x1030, tile_inner,    16);  /* BG slot 3 (well interior)    */
   palette_load(palette);
+
+  /* Draw the cabinet + well into the nametable while rendering is off
+   * (vram_unsafe_set = raw PPU write; the friendly tile_set queue would
+   * deadlock before ppu_on). The grid is 6 wide × 12 tall at pixel origin
+   * (80,16) → tile cols 10..15, rows 2..13; frame it one cell out. We first
+   * tile the WHOLE screen with brick (the machine cabinet), then carve the
+   * recessed well interior, then stamp the steel-blue frame on top — so the
+   * screen is fully covered instead of sprites floating on black. */
+  {
+    uint16_t gx0 = ORIGIN_X / 8, gy0 = ORIGIN_Y / 8;     /* 10, 2  */
+    uint16_t gx1 = gx0 + GRID_W, gy1 = gy0 + GRID_H;     /* 16, 14 (exclusive) */
+    uint16_t cc, rr;
+    /* whole-screen cabinet brick */
+    for (rr = 0; rr < 30; rr++)
+      for (cc = 0; cc < 32; cc++)
+        vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + cc), BG_BRICK);
+    /* recessed well interior (inside the frame) */
+    for (rr = gy0; rr < gy1; rr++)
+      for (cc = gx0; cc < gx1; cc++)
+        vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + cc), BG_INNER);
+    /* steel frame one cell out around the well */
+    for (cc = gx0 - 1; cc <= gx1; cc++) {
+      vram_unsafe_set((uint16_t)(0x2000 + (gy0 - 1) * 32 + cc), BG_WALL); /* top    */
+      vram_unsafe_set((uint16_t)(0x2000 + gy1 * 32 + cc), BG_WALL);       /* bottom */
+    }
+    for (rr = gy0 - 1; rr <= gy1; rr++) {
+      vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + (gx0 - 1)), BG_WALL); /* left   */
+      vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + gx1), BG_WALL);       /* right  */
+    }
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/nes/templates/racing.c

@@ -59,14 +59,22 @@ static const uint8_t tile_digits[10 * 16] = {
 /* ── Background road tiles ───────────────────────────────────────────
  * Default PPUCTRL ($90) reads BG patterns from pattern table 1 ($1000),
  * so these go to CHR $1000+ and are indexed independently of the sprite
- * tiles above. Colour 1 (white, BG palette 0) draws the markings; the
- * grey backdrop (colour 0) is the road surface.
+ * tiles above. The grey backdrop (colour 0) is the road surface; colour 1
+ * (white) draws the markings, colour 2 (green) the grass, colour 3 the
+ * dark seam in the tarmac.
  *
- * BG_T_EDGE: a solid 2px vertical stripe — the road shoulder line.
- * BG_T_LANE: a 2px vertical dash (on for 4 rows, off for 4) — the
- *            dashed centre lane marking when stacked down a column. */
+ * BG_T_EDGE:  a solid 2px vertical stripe — the road shoulder line.
+ * BG_T_LANE:  a 2px vertical dash (on 4 rows / off 4) — the dashed centre
+ *             lane marking when stacked down a column.
+ * BG_T_GRASS: a textured green roadside (colour 2 hatch) so the area
+ *             outside the shoulders isn't flat — fills the screen sides.
+ * BG_T_ROAD:  a faint tarmac texture (a couple of colour-3 specks) tiled
+ *             across the driving surface so the road doesn't read as one
+ *             solid grey block. */
 #define BG_T_EDGE   1
 #define BG_T_LANE   2
+#define BG_T_GRASS  3
+#define BG_T_ROAD   4
 static const uint8_t bg_tile_edge[16] = {
   0x18, 0x18, 0x18, 0x18, 0x18, 0x18, 0x18, 0x18,   /* plane 0 (colour bit 0) */
   0,    0,    0,    0,    0,    0,    0,    0,
@@ -75,13 +83,21 @@ static const uint8_t bg_tile_lane[16] = {
   0x18, 0x18, 0x18, 0x18, 0x00, 0x00, 0x00, 0x00,   /* dash: 4 on, 4 off */
   0,    0,    0,    0,    0,    0,    0,    0,
 };
+static const uint8_t bg_tile_grass[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear */
+  0xEE, 0xBB, 0xEE, 0xBB, 0xEE, 0xBB, 0xEE, 0xBB,   /* plane 1 → colour 2 hatch */
+};
+static const uint8_t bg_tile_road[16] = {
+  0x00, 0x00, 0x10, 0x00, 0x00, 0x08, 0x00, 0x00,   /* plane 0 specks */
+  0x00, 0x00, 0x10, 0x00, 0x00, 0x08, 0x00, 0x00,   /* plane 1 too → colour 3 */
+};
 
 static const uint8_t palette[32] = {
-  /* BG palettes — light grey backdrop simulates road */
-  0x10, 0x30, 0x16, 0x12,
-  0x10, 0x30, 0x16, 0x12,
-  0x10, 0x30, 0x16, 0x12,
-  0x10, 0x30, 0x16, 0x12,
+  /* BG palettes — light grey backdrop simulates road; idx2 = grass green */
+  0x10, 0x30, 0x1A, 0x00,
+  0x10, 0x30, 0x1A, 0x00,
+  0x10, 0x30, 0x1A, 0x00,
+  0x10, 0x30, 0x1A, 0x00,
   /* Sprite palettes */
   0x10, 0x21, 0x16, 0x30,   /* sp0: blue car (P1) */
   0x10, 0x16, 0x21, 0x30,   /* sp1: red enemy */
@@ -125,8 +141,22 @@ static uint8_t aabb(Car *a, Car *b) {
 #define ROAD_DIV_1     13
 #define ROAD_DIV_2     17
 static void draw_road(void) {
-  uint8_t row;
+  uint8_t row, col;
   uint16_t base;
+  /* Fill the WHOLE nametable so nothing reads as flat colour: grass on the
+   * roadside (outside the shoulders) and a faint tarmac texture on the
+   * driving surface. Then stamp the shoulder + lane markings on top. */
+  for (row = 0; row < 30; row++) {
+    base = (uint16_t)(0x2000 + (uint16_t)row * 32);
+    for (col = 0; col < 32; col++) {
+      if (col < ROAD_EDGE_L || col > ROAD_EDGE_R) {
+        vram_unsafe_set((uint16_t)(base + col), BG_T_GRASS);   /* roadside */
+      } else if (((row + col) & 3) == 0) {
+        vram_unsafe_set((uint16_t)(base + col), BG_T_ROAD);    /* tarmac speck */
+      }
+      /* else leave colour-0 grey road surface */
+    }
+  }
   for (row = ROAD_TOP_ROW; row <= ROAD_BOT_ROW; row++) {
     base = (uint16_t)(0x2000 + (uint16_t)row * 32);
     vram_unsafe_set((uint16_t)(base + ROAD_EDGE_L), BG_T_EDGE);
@@ -183,8 +213,10 @@ void main(void) {
 
   /* BG road tiles live in pattern table 1 ($1000) — that's where the
    * default PPUCTRL ($90) tells the PPU to read background patterns. */
-  chr_ram_upload((uint16_t)(0x1000 + BG_T_EDGE * 16), bg_tile_edge, 16);
-  chr_ram_upload((uint16_t)(0x1000 + BG_T_LANE * 16), bg_tile_lane, 16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_EDGE  * 16), bg_tile_edge,  16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_LANE  * 16), bg_tile_lane,  16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_GRASS * 16), bg_tile_grass, 16);
+  chr_ram_upload((uint16_t)(0x1000 + BG_T_ROAD  * 16), bg_tile_road,  16);
 
   palette_load(palette);
   draw_road();          /* paint the static road while the PPU is off */

package/examples/nes/templates/shmup.c

@@ -38,10 +38,34 @@ static const uint8_t tile_enemy[16] = {
   0x81, 0x42, 0x24, 0xFF, 0xFF, 0x24, 0x42, 0x81,  /* plane 0 — spider-ish */
   0,    0,    0,    0,    0,    0,    0,    0,
 };
+/* BG starfield tiles — painted across the whole nametable so the screen
+ * reads as a real "space" scene on boot instead of flat black. They live in
+ * the BACKGROUND pattern table ($1000), separate from the sprite tiles above
+ * (the runtime puts BG at $1000, sprites at $0000).
+ *
+ *   BG_DUST  — a faint checkerboard "space dust" that tiles seamlessly; the
+ *              base layer that covers the whole field so it never reads blank.
+ *   BG_STAR  — three small stars (colour 1) sprinkled over the dust.
+ *   BG_BRITE — a single bright + star (colour 2) for the rare close star. */
+static const uint8_t tile_dust[16] = {
+  0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA,  /* plane 0: checker (idx 1) */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_star[16] = {
+  0x00, 0x08, 0x00, 0x42, 0x00, 0x00, 0x20, 0x01,  /* plane 0: four small stars */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_brite[16] = {
+  0x00, 0x00, 0x10, 0x38, 0x10, 0x00, 0x00, 0x00,  /* plane 0: + arms (idx ... ) */
+  0x00, 0x00, 0x10, 0x38, 0x10, 0x00, 0x00, 0x00,  /* plane 1 set too → colour 3 */
+};
+#define BG_DUST  1   /* BG tile index 1 → uploaded to $1010 */
+#define BG_STAR  2   /* BG tile index 2 → uploaded to $1020 */
+#define BG_BRITE 3   /* BG tile index 3 → uploaded to $1030 */
 
 /* ── Palette ─────────────────────────────────────────────────────── */
 static const uint8_t palette[32] = {
-  /* BG (unused but PPU reads $3F00 backdrop) */
+  /* BG0: backdrop near-black, star colour = dim white */
   0x0F, 0x10, 0x20, 0x30,
   0x0F, 0x10, 0x20, 0x30,
   0x0F, 0x10, 0x20, 0x30,
@@ -126,14 +150,39 @@ void main(void) {
 
   ppu_off();
 
-  /* Upload tile data — blank in slot 0 + 3 sprite tiles in slots 1..3. */
+  /* Upload tile data — blank in slot 0 + 3 sprite tiles in slots 1..3,
+   * all in the SPRITE pattern table ($0000). */
   chr_ram_upload(0x0000, tile_blank,  16);
   chr_ram_upload(0x0010, tile_ship,   16);
   chr_ram_upload(0x0020, tile_bullet, 16);
   chr_ram_upload(0x0030, tile_enemy,  16);
+  /* Upload the starfield tiles to the BACKGROUND pattern table
+   * ($1010/$1020/$1030 = BG slots 1/2/3). */
+  chr_ram_upload(0x1010, tile_dust,   16);
+  chr_ram_upload(0x1020, tile_star,   16);
+  chr_ram_upload(0x1030, tile_brite,  16);
 
   palette_load(palette);
 
+  /* Paint a full starfield directly into the nametable while the PPU is off
+   * (vram_unsafe_set = raw write; tile_set's NMI queue would deadlock
+   * before ppu_on). Every one of the 32×30 cells gets the faint "dust" base,
+   * with small stars sprinkled every few cells and the odd bright star — a
+   * deterministic scatter so the backdrop is unambiguously "space", densely
+   * filled rather than flat black. */
+  {
+    uint16_t r, cc;
+    uint8_t tile;
+    for (r = 0; r < 30; r++) {
+      for (cc = 0; cc < 32; cc++) {
+        tile = BG_DUST;                              /* base dust everywhere */
+        if (((r * 5 + cc * 3) % 7) == 0) tile = BG_STAR;   /* sprinkle stars */
+        if (((r * 3 + cc * 7) % 23) == 0) tile = BG_BRITE; /* rare bright one */
+        vram_unsafe_set((uint16_t)(0x2000 + r * 32 + cc), tile);
+      }
+    }
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/nes/templates/sports.c

@@ -34,6 +34,27 @@ static const uint8_t tile_ball[16] = {
   0x00, 0x3C, 0x7E, 0x7E, 0x7E, 0x7E, 0x3C, 0x00,
   0,    0,    0,    0,    0,    0,    0,    0,
 };
+/* BG court tiles (background pattern table $1000), so the court reads as a
+ * real Pong arena on boot instead of sprites on flat black:
+ *   BG_WALL  — solid bar (idx1 white): the top/bottom rails.
+ *   BG_NET   — dashed vertical bar (idx1 white): the centre net.
+ *   BG_FLOOR — a faint court-floor hatch (idx2 green) tiled across the whole
+ *              playfield so the arena surface is covered, not black. */
+static const uint8_t tile_wall[16] = {
+  0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF,
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_net[16] = {
+  0x18, 0x18, 0x00, 0x00, 0x18, 0x18, 0x00, 0x00,  /* dashed vertical bar */
+  0,    0,    0,    0,    0,    0,    0,    0,
+};
+static const uint8_t tile_floor[16] = {
+  0,    0,    0,    0,    0,    0,    0,    0,        /* plane 0 clear */
+  0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55, 0xAA, 0x55,   /* plane 1 → colour 2 checker */
+};
+#define BG_WALL  1   /* BG slot 1 → $1010 */
+#define BG_NET   2   /* BG slot 2 → $1020 */
+#define BG_FLOOR 3   /* BG slot 3 → $1030 */
 /* Digits 0-9 (3 wide × 5 tall, padded to 8×8). Used for the score HUD. */
 static const uint8_t tile_digits[10 * 16] = {
   /* 0 */ 0xE0,0xA0,0xA0,0xA0,0xE0,0x00,0x00,0x00, 0,0,0,0,0,0,0,0,
@@ -55,11 +76,12 @@ static const uint8_t tile_digits[10 * 16] = {
 #define T_DIGIT0  3   /* digits live at slots 3..12 */
 
 static const uint8_t palette[32] = {
-  /* BG palettes — only the backdrop matters here */
-  0x0F, 0x30, 0x10, 0x00,
-  0x0F, 0x30, 0x10, 0x00,
-  0x0F, 0x30, 0x10, 0x00,
-  0x0F, 0x30, 0x10, 0x00,
+  /* BG0: backdrop near-black, court walls/net = white (idx1),
+   * court-floor hatch = dark green (idx2) */
+  0x0F, 0x30, 0x1A, 0x00,
+  0x0F, 0x30, 0x1A, 0x00,
+  0x0F, 0x30, 0x1A, 0x00,
+  0x0F, 0x30, 0x1A, 0x00,
   /* Sprite palettes */
   0x0F, 0x30, 0x16, 0x12,  /* sp0: white paddle */
   0x0F, 0x30, 0x16, 0x12,  /* sp1: white ball   */
@@ -103,13 +125,36 @@ void main(void) {
 
   ppu_off();
 
-  /* Upload tiles. */
+  /* Upload sprite tiles (sprite pattern table $0000). */
   chr_ram_upload(T_BLANK   * 16, tile_blank,  16);
   chr_ram_upload(T_PADDLE  * 16, tile_paddle, 16);
   chr_ram_upload(T_BALL    * 16, tile_ball,   16);
   chr_ram_upload(T_DIGIT0  * 16, tile_digits, sizeof(tile_digits));
+  /* Upload court tiles to the BACKGROUND pattern table ($1010..$1030). */
+  chr_ram_upload(0x1010, tile_wall,  16);
+  chr_ram_upload(0x1020, tile_net,   16);
+  chr_ram_upload(0x1030, tile_floor, 16);
 
   palette_load(palette);
+
+  /* Paint the court into the nametable while rendering is off
+   * (vram_unsafe_set = raw write). First carpet the whole playfield with the
+   * green floor hatch so the arena surface is covered, then lay the top/
+   * bottom rails (rows 1 and 27) and the dashed centre net (column 15) on
+   * top. Without the floor the screen is just sprites on flat black. */
+  {
+    uint16_t cc, rr;
+    for (rr = 0; rr < 30; rr++)
+      for (cc = 0; cc < 32; cc++)
+        vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + cc), BG_FLOOR);
+    for (cc = 0; cc < 32; cc++) {
+      vram_unsafe_set((uint16_t)(0x2000 + 1 * 32 + cc),  BG_WALL);  /* top rail (y≈8)   */
+      vram_unsafe_set((uint16_t)(0x2000 + 27 * 32 + cc), BG_WALL);  /* bottom rail(y≈216)*/
+    }
+    for (rr = 2; rr < 27; rr++)
+      vram_unsafe_set((uint16_t)(0x2000 + rr * 32 + 15), BG_NET);   /* centre net       */
+  }
+
   oam_clear();
   ppu_on_all();
   sound_init();

package/examples/pce/platformer/main.c

@@ -0,0 +1,283 @@
+/*
+ * PC Engine "platformer" — a side-scrolling platformer scaffold.
+ *
+ * Run and jump across a world wider than one screen. The d-pad moves left/right,
+ * button I jumps; gravity pulls you down and you land on top of solid platforms.
+ * The camera follows the player and the background scrolls smoothly via the VDC
+ * background X-scroll register (BXR/R7).
+ *
+ * The PCE BAT (background map) is a 32x32 virtual screen (256px) that WRAPS, so
+ * a world wider than 256px needs COLUMN STREAMING: each time the camera crosses
+ * an 8px boundary we rewrite the BAT column that is about to scroll into view
+ * with the next world column's tiles. This mirrors the SMS platformer scaffold,
+ * using BXR instead of SMS R8.
+ *
+ * PCE notes (see pce_hw.h / MENTAL_MODEL.md):
+ *   - disp_enable() turns on BG + sprites + the VBlank IRQ (waitvsync needs it).
+ *   - .bss must be non-empty (pce_video.c's _pce_keep[] covers it).
+ *   - we set BXR every frame via vdc_set_reg(VDC_BXR, camX) for smooth scroll.
+ *
+ * cc65 is C89 — declare locals at the top of a block.
+ */
+#include <pce.h>
+#include <stdint.h>   /* int8_t/int16_t/int32_t for sub-pixel physics + camera */
+#include "pce_hw.h"
+
+/* ---- VRAM layout (word addresses) --------------------------------------- */
+#define BAT_VRAM     0x0000   /* 32x32 background map                        */
+#define SKY_VRAM     0x1000   /* BG tile: sky (solid colour 1)               */
+#define WALL_VRAM    0x1010   /* BG tile: platform block (colour 2)          */
+#define WALLTOP_VRAM 0x1020   /* BG tile: platform top edge (colour 3 strip) */
+#define PLAYER_VRAM  0x1800   /* 16x16 player                                */
+
+#define BAT_ENTRY(pal, vram)  ((u16)(((pal) << 12) | ((vram) >> 4)))
+
+/* ---- world -------------------------------------------------------------- */
+#define WORLD_COLS  96            /* 96 cells = 768 px world                  */
+#define WORLD_W     (WORLD_COLS * 8)
+#define SCREEN_W    256
+#define VIS_ROWS    28            /* 224-line display = 28 rows               */
+
+typedef struct { int16_t x, y, w, h; } Rect;
+
+/* Platforms in WORLD pixel coords, spread across the 768px world. */
+static const Rect platforms[] = {
+    {   0, 200, 768, 24 },   /* floor spans the world          */
+    {  48, 168,  56,  8 },
+    { 140, 152,  64,  8 },
+    { 232, 128,  56,  8 },
+    {  96, 112,  40,  8 },
+    { 320, 160,  72,  8 },
+    { 416, 128,  64,  8 },
+    { 360,  88,  48,  8 },
+    { 512, 152,  80,  8 },
+    { 600, 120,  56,  8 },
+    { 672, 168,  72,  8 },
+    { 560,  80,  48,  8 }
+};
+#define N_PLATFORMS (sizeof(platforms) / sizeof(platforms[0]))
+
+/* ---- state -------------------------------------------------------------- */
+static int16_t px, py;        /* player position in 1/16-px units            */
+static int16_t vx, vy;
+static int16_t camX, lastCamCol;
+static u8 pad, prev_pad;
+static u16 spr_buf[64];
+static u16 tile_buf[16];
+
+static void make_solid_tile(u16 *t, u8 ci) {
+    u8 r;
+    u8 p0 = (ci & 1) ? 0xFF : 0x00;
+    u8 p1 = (ci & 2) ? 0xFF : 0x00;
+    u8 p2 = (ci & 4) ? 0xFF : 0x00;
+    u8 p3 = (ci & 8) ? 0xFF : 0x00;
+    for (r = 0; r < 8; ++r) {
+        t[r]     = (u16)(p0 | (p1 << 8));
+        t[r + 8] = (u16)(p2 | (p3 << 8));
+    }
+}
+
+/* platform-top tile: colour 2 body with a colour-3 highlight on the top 2 rows */
+static void make_walltop_tile(u16 *t) {
+    make_solid_tile(t, 2);
+    /* rows 0,1: set plane0 too so those pixels read colour 3 (planes0+1) */
+    t[0] = (u16)(0x00FF | (t[0] & 0xFF00));
+    t[1] = (u16)(0x00FF | (t[1] & 0xFF00));
+}
+
+static void make_player_sprite(void) {
+    static const u16 body[16] = {
+        0x07E0, 0x0FF0, 0x1FF8, 0x1818, 0x1FF8, 0x1FF8, 0x3FFC, 0x7FFE,
+        0x7FFE, 0x7FFE, 0x3FFC, 0x1FF8, 0x0E70, 0x0C30, 0x0C30, 0x1818
+    };
+    static const u16 eyes[16] = {
+        0x0000, 0x0000, 0x0000, 0x0000, 0x0990, 0x0990, 0x0000, 0x0000,
+        0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000, 0x0000
+    };
+    u8 r;
+    for (r = 0; r < 64; ++r) spr_buf[r] = 0;
+    for (r = 0; r < 16; ++r) {
+        spr_buf[r]      = (u16)(body[r] & ~eyes[r]);   /* plane0 -> colour 1 */
+        spr_buf[r + 16] = eyes[r];                     /* plane1 -> colour 2 */
+    }
+    load_tiles(PLAYER_VRAM, spr_buf, 64);
+}
+
+/* Is world cell (col,row) inside any platform? */
+static u8 cell_is_wall(int16_t col, u8 row) {
+    int16_t cx = (int16_t)(col << 3);
+    int16_t cy = (int16_t)((int16_t)row << 3);
+    u8 i;
+    const Rect *p;
+    for (i = 0; i < N_PLATFORMS; ++i) {
+        p = &platforms[i];
+        if (cx + 8 > p->x && cx < p->x + p->w &&
+            cy + 8 > p->y && cy < p->y + p->h) return 1;
+    }
+    return 0;
+}
+
+/* Is world cell the TOP row of a platform (for the highlighted edge tile)? */
+static u8 cell_is_top(int16_t col, u8 row) {
+    int16_t cy = (int16_t)((int16_t)row << 3);
+    int16_t cx = (int16_t)(col << 3);
+    u8 i;
+    const Rect *p;
+    for (i = 0; i < N_PLATFORMS; ++i) {
+        p = &platforms[i];
+        if (cx + 8 > p->x && cx < p->x + p->w && cy >= p->y && cy < p->y + 8) return 1;
+    }
+    return 0;
+}
+
+/* Write one world column into its wrapped BAT column. */
+static void paint_column(int16_t worldCol) {
+    u8 ntCol, row;
+    u16 e;
+    if (worldCol < 0 || worldCol >= WORLD_COLS) return;
+    ntCol = (u8)(worldCol & 31);
+    for (row = 0; row < 32; ++row) {
+        if (row < VIS_ROWS && cell_is_wall(worldCol, row)) {
+            e = cell_is_top(worldCol, row)
+                ? BAT_ENTRY(0, WALLTOP_VRAM)
+                : BAT_ENTRY(0, WALL_VRAM);
+        } else {
+            e = BAT_ENTRY(0, SKY_VRAM);
+        }
+        vram_set_write_addr((u16)(BAT_VRAM + row * 32 + ntCol));
+        VDC_DATA_LO = (u8)(e & 0xFF);
+        VDC_DATA_HI = (u8)(e >> 8);
+    }
+}
+
+static void paint_initial(void) {
+    int16_t c;
+    for (c = 0; c < 32; ++c) paint_column(c);
+}
+
+static u8 on_platform(int16_t ipx, int16_t ipy) {
+    u8 i;
+    const Rect *p;
+    for (i = 0; i < N_PLATFORMS; ++i) {
+        p = &platforms[i];
+        if (ipy + 16 == p->y && ipx + 12 > p->x && ipx + 4 < p->x + p->w) return 1;
+    }
+    return 0;
+}
+
+void main(void) {
+    const int16_t GRAVITY = 10;
+    const int16_t MOVE    = 22;
+    const int16_t JUMP    = -200;
+    const int16_t MAXFALL = 300;
+
+    _pce_keep[0] = 0;
+
+    /* palette */
+    vce_set_color(0,   PCE_RGB(1, 2, 5));   /* backdrop sky blue            */
+    vce_set_color(1,   PCE_RGB(2, 4, 7));   /* BG c1: sky                   */
+    vce_set_color(2,   PCE_RGB(3, 2, 1));   /* BG c2: brown platform        */
+    vce_set_color(3,   PCE_RGB(1, 6, 1));   /* BG c3: green grassy top      */
+    vce_set_color(256, PCE_RGB(0, 0, 0));   /* spr transparent              */
+    vce_set_color(257, PCE_RGB(7, 1, 1));   /* spr c1: red body             */
+    vce_set_color(258, PCE_RGB(7, 7, 7));   /* spr c2: white eyes           */
+
+    make_solid_tile(tile_buf, 1); load_tiles(SKY_VRAM, tile_buf, 16);
+    make_solid_tile(tile_buf, 2); load_tiles(WALL_VRAM, tile_buf, 16);
+    make_walltop_tile(tile_buf);  load_tiles(WALLTOP_VRAM, tile_buf, 16);
+    make_player_sprite();
+
+    paint_initial();
+
+    px = (int16_t)(24 << 4);
+    py = (int16_t)(160 << 4);
+    vx = 0; vy = 0;
+    camX = 0; lastCamCol = 0;
+    prev_pad = 0;
+
+    set_sprite(0, (u16)(px >> 4), (u16)(py >> 4), PLAYER_VRAM >> 6, 0);
+    satb_dma();
+
+    pce_joy_init();
+    disp_enable();
+
+    for (;;) {
+        int16_t ipx, ipy, npy, sx;
+        int16_t camCol;
+        int32_t np;
+        u8 grounded;
+        u8 i;
+        const Rect *p;
+
+        waitvsync();
+        pad = pce_joy_read();
+
+        ipx = px >> 4;
+        ipy = py >> 4;
+
+        /* camera follows player, clamped to world */
+        camX = (int16_t)(ipx - (SCREEN_W / 2 - 8));
+        if (camX < 0) camX = 0;
+        if (camX > WORLD_W - SCREEN_W) camX = (int16_t)(WORLD_W - SCREEN_W);
+
+        /* stream columns entering from the edges */
+        camCol = camX >> 3;
+        while (camCol > lastCamCol) { lastCamCol++; paint_column((int16_t)(lastCamCol + 31)); }
+        while (camCol < lastCamCol) { lastCamCol--; paint_column(lastCamCol); }
+
+        /* smooth pixel scroll via BG X register */
+        vdc_set_reg(VDC_BXR, (u16)camX);
+
+        /* horizontal move */
+        vx = 0;
+        if (pad & PCE_JOY_LEFT)  vx = (int16_t)(-MOVE);
+        if (pad & PCE_JOY_RIGHT) vx = MOVE;
+
+        grounded = on_platform(ipx, ipy);
+        if ((pad & PCE_JOY_I) && !(prev_pad & PCE_JOY_I) && grounded) {
+            vy = JUMP;
+            psg_tone(0, 0x200, 24);
+        }
+        prev_pad = pad;
+
+        vy = (int16_t)(vy + GRAVITY);
+        if (vy > MAXFALL) vy = MAXFALL;
+        if (grounded && vy > 0) vy = 0;
+
+        /* horizontal integrate + clamp */
+        px = (int16_t)(px + vx);
+        if (px < 0) px = 0;
+        if (px > ((WORLD_W - 16) << 4)) px = (int16_t)((WORLD_W - 16) << 4);
+
+        /* vertical integrate with land-on-top */
+        np = (int32_t)py + (int32_t)vy;
+        npy = (int16_t)(np >> 4);
+        if (vy > 0) {
+            u8 landed = 0;
+            for (i = 0; i < N_PLATFORMS; ++i) {
+                p = &platforms[i];
+                if (ipy + 16 <= p->y && npy + 16 >= p->y &&
+                    ipx + 12 > p->x && ipx + 4 < p->x + p->w) {
+                    py = (int16_t)((p->y - 16) << 4);
+                    vy = 0;
+                    landed = 1;
+                    break;
+                }
+            }
+            if (!landed) py = (int16_t)np;
+        } else {
+            py = (int16_t)np;
+        }
+        if (py > (224 << 4)) { px = (int16_t)(24 << 4); py = (int16_t)(160 << 4); vy = 0; }
+
+        /* free the jump SFX channel after it rings */
+        if (vy == 0) psg_off(0);
+
+        /* draw player in screen space */
+        sx = (int16_t)((px >> 4) - camX);
+        if (sx < 0) sx = 0;
+        if (sx > 240) sx = 240;
+        set_sprite(0, (u16)sx, (u16)(py >> 4), PLAYER_VRAM >> 6, 0);
+        satb_dma();
+    }
+}