romdevtools 0.28.0 → 0.29.0

package/examples/gbc/templates/puzzle.c

@@ -1,45 +1,76 @@
-/* PUZZLE — a falling-jewel matcher for Game Boy Color.
+/* ── puzzle.c — CHROMA WELL: Game Boy Color falling-jewel matcher (complete example game) ──
  *
- * A vertical column of 3 jewels falls into an 8-wide x 17-tall well.  Move it
- * left/right, soft-drop (Down), hard-drop (Start), and CYCLE the three colors
- * (A/B).  Line up 3+ of one color horizontally, vertically, or diagonally to
- * clear them; gravity pulls the survivors down, which can chain.  Every 18th
- * piece is a MAGIC jewel that clears every gem of the color it lands on.
- * SELECT toggles the background music.
+ * A COMPLETE, working game — title screen, persistent battery hi-score
+ * (MBC1+RAM+BATTERY SRAM), music + SFX, and the GBC's signature feature:
+ * TRUE per-tile color. Six jewel types are six REAL CGB palettes (15-bit
+ * BGR, loaded through BCPS/BCPD + OCPS/OCPD), selected per BG cell through
+ * the VRAM bank-1 attribute map and per sprite through OAM attribute bits —
+ * not a colorized monochrome game.
+ *
+ * THE GAME: a vertical column of 3 jewels falls into an 8-wide x 15-tall
+ * well. Move it left/right, soft-drop (Down), hard-drop (Start), and CYCLE
+ * the three colors (A/B). Line up 3+ of one color horizontally, vertically,
+ * or diagonally to clear; gravity pulls survivors down, which can chain.
+ * Every 18th piece is a MAGIC jewel that clears every gem of the color it
+ * lands on. SELECT toggles the music.
+ *
+ * THIS FILE IS MEANT TO BE FORKED AND MODIFIED into your own game — even a
+ * very different one. The markers tell you what's what:
+ *   HARDWARE IDIOM (load-bearing) — dodges a documented GB/GBC footgun;
+ *     reshape your gameplay around it (see TROUBLESHOOTING before changing).
+ *   GAME LOGIC (clay) — board rules, scoring, tuning, art: reshape freely.
+ *
+ * SINGLE-PLAYER, honestly: the Game Boy's "player 2" is a LINK CABLE, which
+ * one emulator instance cannot provide — so handheld examples ship a
+ * press-start title and no 2P mode instead of faking one.
+ *
+ * What depends on what:
+ *   gb_runtime.{h,c} — vblank/joypad/OAM-DMA/sound library (shared with GB).
+ *   gb_crt0.s — boot + header window. It DECLARES the cart as
+ *     MBC1+RAM+BATTERY ($0147=$03, $0149=$02): that header is what makes
+ *     the SRAM hi-score persist (the GB equivalent of the NES BATTERY bit).
+ *   font.h — 0-9 A-Z glyphs for all text.
  *
  * RENDERING — the hard-won architecture (details at each routine below):
  *  - The FALLING column and the NEXT preview are OBJ sprites (OAM), not BG
  *    tiles, so moving them is just an OAM rewrite — no per-frame BG writes.
- *  - The LOCKED well + HUD are BG tiles, updated through a COLLECT/FLUSH queue:
- *    redraw_collect() decides what to write (RAM only); redraw_flush() writes a
- *    few cells to VRAM as the very first thing in vblank.  The whole per-frame
- *    job (OAM DMA + flush) MUST finish inside the ~10-line vblank window —
- *    overrunning into active display silently DROPS writes on this core, which
- *    is exactly what made the screen disagree with the board.  An idle "scrub"
- *    continuously repaints the well from the grid so nothing can drift.
- *  - We NEVER toggle the LCD in-game (this core blanks the whole frame on any
- *    LCDC bit-7 toggle — a strobe).  LCD-off is used only for the full-screen
- *    title <-> game transitions.
+ *  - The LOCKED well is BG tiles, updated through a COLLECT/FLUSH queue:
+ *    redraw_collect() decides what to write (RAM only); redraw_flush()
+ *    writes a few cells to VRAM as the very first thing in vblank. The whole
+ *    per-frame job (OAM DMA + flush) MUST finish inside the ~10-line vblank
+ *    window — overrunning into active display silently DROPS writes on this
+ *    core. An idle "scrub" continuously repaints the well from the grid so
+ *    nothing can drift.
+ *  - The HUD (score / hi-score / level) lives on the WINDOW layer — a fixed
+ *    strip at the bottom of the screen, immune to BG scrolling.
+ *  - We NEVER toggle the LCD in-game (this core blanks the whole frame on
+ *    any LCDC bit-7 toggle — a strobe). LCD-off is used only for the
+ *    full-screen title <-> game transitions.
  *
  * WRAM NOTE: build with dataLoc:0xC200 so our statics sit ABOVE shadow_oam
- * ($C100) — else oam_clear() would zero our state (RNG seed / grid).
+ * ($C100) — else oam_clear() would zero our state (RNG seed / grid). The
+ * project build recipe sets that automatically.
  */
 #include "gb_hardware.h"
 #include "gb_runtime.h"
 #include "font.h"
 
+/* The title screen renders this — examples({op:'fork'}) stamps your game's
+ * name here automatically. Keep it ≤16 chars of A-Z 0-9 space dash. */
+#define GAME_TITLE "CHROMA WELL"
+
+/* ── GAME LOGIC (clay — reshape freely) ── board geometry */
 #define COLS      8
-#define ROWS      17
+#define ROWS      15         /* rows 0-14; floor at map row 15; window HUD rows 16-17 */
 #define NCELL     (ROWS * COLS)
-#define NCOLORS   6          /* jewel colors 1..6 */
+#define NCOLORS   6          /* jewel colors 1..6 — one CGB palette each */
 
 /* BG map cell of interior grid cell (0,0) — the well's top-left corner.
- * Open at the top (row 0); walls sit one cell outside on the left/right and
- * below the bottom (floor at WELL_MY+ROWS = row 17, the last screen row). */
+ * Open at the top (row 0); walls one cell outside left/right, floor below. */
 #define WELL_MX   1
 #define WELL_MY   0
 
-/* BG map column where the HUD text starts (right of the well). */
+/* BG map column where the right-hand panel (NEXT preview) starts. */
 #define HUD_X     12
 
 #define G(r,c)    grid[((r) * COLS) + (c)]
@@ -60,13 +91,20 @@
 #define PAL_WELL  6
 #define PAL_OUT   7
 
-#define ST_PLAY   0
-#define ST_OVER   1
-#define ST_TITLE  2
+#define ST_TITLE  0
+#define ST_PLAY   1
+#define ST_OVER   2
 
 #define VRAM ((volatile uint8_t *)0x9800)
-
-/* ── tile pixel data (2bpp) ────────────────────────────────────────── */
+/* The window layer fetches from the $9C00 map — offset $400 past $9800 in
+ * the same VRAM pointer (see the WINDOW HUD idiom below). */
+#define WIN_OFF   0x400
+
+/* ── GAME LOGIC (clay — reshape freely) ── tile pixel data (2bpp).
+ * Each 8x8 tile = 16 bytes, 2 bytes per row (plane 0 then plane 1); a pixel's
+ * 2-bit color value indexes into whichever CGB palette the cell's attribute
+ * byte (BG) or the sprite's OAM attr (OBJ) selects. ONE gem tile becomes six
+ * different-colored gems purely through palette selection. */
 static const uint8_t tile_empty[16] = {
     0x00,0x00, 0x22,0x00, 0x00,0x00, 0x88,0x00,
     0x00,0x00, 0x22,0x00, 0x00,0x00, 0x88,0x00,
@@ -100,7 +138,9 @@ static const uint8_t tile_exp2[16] = {
     0x00,0x00, 0x00,0x00, 0x00,0x00, 0x00,0x81,
 };
 
-/* ── palettes (15-bit BGR) ─────────────────────────────────────────── */
+/* ── GAME LOGIC (clay — reshape freely) ── the palette TABLE (the colors
+ * themselves are art; the LOADER below is the hardware idiom).
+ * 15-bit BGR: 5 bits each, blue in the high bits — RGB() packs it. */
 #define RGB(r,g,b) ((uint16_t)(((uint16_t)(b)<<10)|((uint16_t)(g)<<5)|(r)))
 #define C_WELL  RGB(4,6,12)
 #define C_OUT   RGB(1,2,4)
@@ -118,7 +158,7 @@ static const uint16_t palettes[8][4] = {
     /* 7 out/txt*/ { C_OUT,  RGB(2,3,7),    C_OUT,         RGB(31,31,31) },
 };
 
-/* ── game state ────────────────────────────────────────────────────── */
+/* ── GAME LOGIC (clay — reshape freely) ── game state */
 static uint8_t grid[NCELL];         /* the well: 0 = empty, 1..NCOLORS = a gem */
 static uint8_t matched[NCELL];      /* scratch: cells flagged for clearing */
 static uint8_t shadow[NCELL];       /* color currently on the BG, for diff redraw */
@@ -134,7 +174,8 @@ static uint8_t cur_fall_rate;       /* frames per downward step (lower = faster)
 static uint16_t total_cleared;      /* gems cleared this game (drives level) */
 static uint8_t level;
 static uint8_t score_d[6];          /* 6-digit BCD score, most significant first */
-static uint8_t state;               /* ST_PLAY / ST_OVER / ST_TITLE */
+static uint8_t hi_d[6];             /* 6-digit BCD hi-score (battery SRAM) */
+static uint8_t state;               /* ST_TITLE / ST_PLAY / ST_OVER */
 static uint8_t chain;               /* cascade depth of the current resolve */
 static uint16_t rng = 0xACE1;       /* xorshift PRNG state */
 
@@ -171,12 +212,79 @@ static void add_score(uint16_t amt) {
     }
 }
 
-/* ── sound effects ──────────────────────────────────────────────────
+/* most-significant-digit-first BCD compare: did this run beat the record? */
+static uint8_t score_beats_hi(void) {
+    uint8_t i;
+    for (i = 0; i < 6; i++) {
+        if (score_d[i] > hi_d[i]) return 1;
+        if (score_d[i] < hi_d[i]) return 0;
+    }
+    return 0;
+}
+
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * BATTERY SRAM hi-score — persistent saves on a Game Boy cart.
+ * requires: gb_crt0.s declaring MBC1+RAM+BATTERY in the cartridge header
+ *   ($0147=$03, $0149=$02 → 8KB at $A000-$BFFF). With a ROM-only header the
+ *   $A000 region is OPEN BUS: writes vanish, reads return garbage, and
+ *   nothing tells you why. The header is the save system.
+ *
+ * The MBC powers up with cart RAM DISABLED (protection against corrupting
+ * the battery RAM with stray bus traffic while power rails settle). The
+ * $0A-enable dance:
+ *   1. write $0A to anywhere in $0000-$1FFF  → RAM enabled
+ *   2. read/write $A000-$BFFF                → real battery RAM
+ *   3. write $00 to $0000-$1FFF              → RAM disabled again
+ * ALWAYS re-disable after access — that's what makes a yanked cartridge /
+ * dying battery corrupt at most the bytes mid-write, not the whole save.
+ *
+ * First boot is GARBAGE, not zeros: battery RAM holds whatever the silicon
+ * woke up with. The magic bytes + XOR checksum below are how the load path
+ * tells "my save" from "factory noise" — without them a fresh cart shows a
+ * junk hi-score like 974382.
+ *
+ * Save block at $A000: 'H' 'S'  d0 d1 d2 d3 d4 d5  ck
+ *   (6 BCD digits, most significant first; ck = d0^..^d5^$A5)
+ * No timing constraints — SRAM is not VRAM; access it any time. */
+#define SRAM_BASE ((volatile uint8_t *)0xA000)
+#define MBC_RAMG  (*(volatile uint8_t *)0x0000)   /* MBC1 RAM-gate register */
+
+static void hiscore_load(void) {
+    uint8_t i, ck;
+    MBC_RAMG = 0x0A;                          /* enable cart RAM */
+    ck = 0xA5;
+    for (i = 0; i < 6; i++) ck ^= SRAM_BASE[2 + i];
+    if (SRAM_BASE[0] == 'H' && SRAM_BASE[1] == 'S' && SRAM_BASE[8] == ck) {
+        for (i = 0; i < 6; i++) {
+            hi_d[i] = SRAM_BASE[2 + i];
+            if (hi_d[i] > 9) hi_d[i] = 9;     /* belt + braces on a bad digit */
+        }
+    } else {
+        for (i = 0; i < 6; i++) hi_d[i] = 0;  /* first boot / corrupt → 0 */
+    }
+    MBC_RAMG = 0x00;                          /* ALWAYS re-disable */
+}
+
+static void hiscore_save(void) {
+    uint8_t i, ck;
+    MBC_RAMG = 0x0A;
+    SRAM_BASE[0] = 'H';
+    SRAM_BASE[1] = 'S';
+    ck = 0xA5;
+    for (i = 0; i < 6; i++) {
+        SRAM_BASE[2 + i] = hi_d[i];
+        ck ^= hi_d[i];
+    }
+    SRAM_BASE[8] = ck;
+    MBC_RAMG = 0x00;
+}
+
+/* ── GAME LOGIC (clay — reshape freely) ── sound effects.
  * A tiny note sequencer driving square channel 2 directly.  Each note has
  * a real volume-decay envelope (NR22) so it fades instead of clicking off
- * (the old sound_play_tone hard-cut every note — that was the "static").
- * sfx_tick() advances one step per frame; multi-note effects become little
- * arpeggios.  GB period p ⇒ freq = 131072/(2048-p); higher p = higher note. */
+ * (a hard NRx2=0 cut every note sounds like static).  sfx_tick() advances
+ * one step per frame; multi-note effects become little arpeggios.
+ * GB period p ⇒ freq = 131072/(2048-p); higher p = higher note. */
 #define P_C4  1548
 #define P_G4  1714
 #define P_A4  1750
@@ -242,7 +350,7 @@ static void sfx_over(void) {       /* slow descending */
     sfx_go(3);
 }
 
-/* ── background music ───────────────────────────────────────────────
+/* ── GAME LOGIC (clay — reshape freely) ── background music.
  * A looping square-wave lead on channel 1 (SFX live on channel 2, so they
  * mix and the effects cut through the music).  music_tick() plays one melody
  * step every 12 frames, re-triggering ch1 at a steady volume.  Toggle on/off
@@ -294,6 +402,8 @@ static void music_toggle(void) {
     if (!music_on) { NR12 = 0x00; NR14 = 0x80; }   /* kill the lead immediately */
 }
 
+/* ── GAME LOGIC (clay — reshape freely) ── board mechanics */
+
 /* is grid cell (r,col) off the bottom or already filled? */
 static uint8_t cell_blocked(uint8_t r, uint8_t col) {
     if (r >= ROWS) return 1;
@@ -311,6 +421,8 @@ static uint8_t collides(uint8_t col, uint8_t topy) {
     return 0;
 }
 
+static void game_over(void);
+
 /* start a new falling column at the top-center.  Every 18th piece is a MAGIC
  * column; otherwise take the previewed colors and roll the next preview.  If
  * it can't even appear, the well is full → game over. */
@@ -330,10 +442,7 @@ static void spawn(void) {
     piece_active = 1;
     fall_timer = 0;
     next_dirty = 1;
-    if (collides(piece_x, piece_y)) {
-        piece_active = 0;
-        state = ST_OVER;
-    }
+    if (collides(piece_x, piece_y)) game_over();
 }
 
 /* Flag every gem that's part of a run of 3+ same-color cells in any of the 4
@@ -423,7 +532,7 @@ static void explode_matched(void) {
     uint16_t offs[8];
     uint8_t  cols[8];
     uint8_t *o = (uint8_t *)0xC100;
-    for (i = 0; i < 12; i++) *o++ = 0;             /* hide the locked piece sprites */
+    for (i = 0; i < 12; i++) *o++ = 0;             /* hide the falling-piece sprites */
     ((void (*)(uint8_t))0xFF80)(0xC1);
     n = 0;
     for (i = 0; i < NCELL && n < 8; i++) {
@@ -513,10 +622,25 @@ static void upload_tile(uint8_t slot, const uint8_t *src) {
     memcpy_vram((uint8_t *)(0x8000 + slot * 16), src, 16);
 }
 
-/* push all 8 BG palettes (4 colors each, 15-bit BGR) via the BCPS/BCPD port */
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * CGB palette RAM — the BCPS/BCPD (BG) and OCPS/OCPD (OBJ) port pairs.
+ * requires: a .gbc build (CGB flag $0143 set — the build pipeline does it);
+ *   on a DMG build these registers are dead and you get 4-shade green.
+ *
+ * Palette RAM is NOT memory-mapped: it's 64 bytes (8 palettes × 4 colors ×
+ * 2 bytes, little-endian 15-bit BGR) behind an index/data port pair.
+ *   BCPS = 0x80 | index   — set write index; bit 7 = AUTO-INCREMENT, so a
+ *                           burst of BCPD writes walks the whole 64 bytes.
+ *   BCPD = low byte; BCPD = high byte;  ... 32 times = all 8 palettes.
+ *
+ * TIMING FOOTGUN: palette RAM belongs to the PPU. Writes during active
+ * display (mode 3) are IGNORED on real hardware — same constraint as VRAM.
+ * Load palettes with the LCD OFF (boot / transitions, as here) or inside
+ * vblank. A palette "fade" effect = a few BCPD writes per vblank, never a
+ * mid-frame burst. */
 static void load_palettes(void) {
     uint8_t p, i;
-    BCPS = 0x80;
+    BCPS = 0x80;                       /* index 0, auto-increment on */
     for (p = 0; p < 8; p++)
         for (i = 0; i < 4; i++) {
             BCPD = (uint8_t)(palettes[p][i] & 0xFF);
@@ -524,8 +648,9 @@ static void load_palettes(void) {
         }
 }
 
-/* OBJ palettes: 0-5 = jewels (light/main/dark), 6 = magic white. Color 0 of
- * every OBJ palette is transparent (sprite shows the well behind it). */
+/* OBJ palettes 0-5 = the six jewel colors (same table as the BG, so a
+ * falling gem matches its locked twin exactly), 6 = magic white.  Color 0
+ * of every OBJ palette is transparent (the well shows through). */
 static void load_obj_palettes(void) {
     uint8_t p, i;
     uint16_t col;
@@ -541,9 +666,11 @@ static void load_obj_palettes(void) {
 }
 
 /* The falling column = sprites 0-2; the NEXT preview = sprites 3-5 (sprites
- * so their transparent corners blend with the dark HUD).  Then flush OAM.
+ * so their transparent corners blend with the panel).  Then flush OAM.
  * MUST be the first VRAM/OAM work after wait_vblank: the OAM DMA has to
- * land in vblank, or sprites tear on a fixed scanline near the top. */
+ * land in vblank, or sprites tear on a fixed scanline near the top.
+ * A sprite's CGB palette = OAM attr bits 0-2 — that's the whole "color this
+ * sprite" story (we write piece[i]-1 straight into the attr byte). */
 static void update_sprites(void) {
     /* Write shadow_oam ($C100) directly with a walking pointer — calling
      * oam_set() six times burns ~10 scanlines of vblank (SDCC call overhead),
@@ -570,9 +697,9 @@ static void update_sprites(void) {
         if (state == ST_TITLE) {
             for (i = 0; i < 12; i++) *o++ = 0;
         } else {
-            sx = (uint8_t)((HUD_X + 2) * 8 + 8);
+            sx = (uint8_t)((HUD_X + 1) * 8 + 8);
             for (i = 0; i < 3; i++) {
-                *o++ = (uint8_t)((9 + i) * 8 + 16);
+                *o++ = (uint8_t)((3 + i) * 8 + 16);
                 *o++ = sx;
                 *o++ = T_GEM;
                 *o++ = (uint8_t)(nextp[i] - 1);
@@ -584,8 +711,28 @@ static void update_sprites(void) {
     ((void (*)(uint8_t))0xFF80)(0xC1);
 }
 
-/* write one BG map cell: tile index (VRAM bank 0) + palette/attr (bank 1).
- * Direct, unbounded — only safe with the LCD off or in a bounded vblank batch. */
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * Per-tile color — the VRAM bank-1 attribute map (VBK register).
+ * requires: CGB mode (see the palette idiom above); writes in a VRAM-safe
+ *   window (LCD off, or a bounded vblank batch like redraw_flush).
+ *
+ * VRAM is TWO 8KB banks behind the same $8000-$9FFF window; VBK ($FF4F)
+ * selects which one the CPU sees. Bank 0 holds what the DMG had: tile
+ * pixels + the tile-index maps. Bank 1 at the SAME map address holds one
+ * ATTRIBUTE byte per cell:
+ *   bits 0-2  palette 0-7   ← this game's whole color system
+ *   bit 3     tile VRAM bank
+ *   bit 5/6   H/V flip
+ *   bit 7     BG-over-OBJ priority
+ * So coloring a cell is a write PAIR: tile index with VBK=0, attribute with
+ * VBK=1, at the SAME offset.
+ *
+ * FOOTGUN: VBK is global state. Forget to restore VBK=0 and every later
+ * "tile" write lands in the attribute map — the screen turns into garbage
+ * colors while the tile data you wrote is simply gone. Always end VBK=0
+ * (every routine here does).
+ * (Direct, unbounded — only safe with the LCD off or in a bounded vblank
+ * batch; the in-game path queues instead — see redraw_collect/flush.) */
 static void set_cell(uint8_t mx, uint8_t my, uint8_t tile, uint8_t pal) {
     uint16_t off = (uint16_t)my * 32 + mx;
     VBK = 0;
@@ -595,6 +742,16 @@ static void set_cell(uint8_t mx, uint8_t my, uint8_t tile, uint8_t pal) {
     VBK = 0;
 }
 
+/* same write-pair, into the WINDOW's map at $9C00 (see the window idiom) */
+static void set_wcell(uint8_t wx, uint8_t wy, uint8_t tile, uint8_t pal) {
+    uint16_t off = WIN_OFF + (uint16_t)wy * 32 + wx;
+    VBK = 0;
+    VRAM[off] = tile;
+    VBK = 1;
+    VRAM[off] = pal;
+    VBK = 0;
+}
+
 /* map an ASCII char to its font tile slot (digits, then A-Z); blank otherwise */
 static uint8_t font_slot(char ch) {
     if (ch >= '0' && ch <= '9') return FONT_BASE + (uint8_t)(ch - '0');
@@ -609,19 +766,69 @@ static void draw_text(uint8_t col, uint8_t row, const char *s) {
         set_cell((uint8_t)(col + i), row, font_slot(s[i]), PAL_OUT);
 }
 
-/* Only the DYNAMIC HUD values (~11 cells) — the labels are static, drawn
- * once in draw_static.  Small enough to write inside one vblank. */
-static void draw_hud(void) {
+/* draw a NUL-terminated string into the WINDOW map starting at (col,row) */
+static void draw_wtext(uint8_t col, uint8_t row, const char *s) {
+    uint8_t i;
+    for (i = 0; s[i] != 0; i++)
+        set_wcell((uint8_t)(col + i), row, font_slot(s[i]), PAL_OUT);
+}
+
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * WINDOW-layer HUD — a fixed strip the BG scroll can never move.
+ * requires: LCDC bits 5 (window on) + 6 (window map = $9C00), WX/WY set,
+ *   and HUD text written to the $9C00 map (set_wcell), not the $9800 one.
+ *
+ * The window is the GB's second BG plane: same tile data, its OWN 32x32
+ * map, drawn OVER the BG starting at screen position (WX-7, WY) and
+ * extending to the bottom-right. It ignores SCX/SCY completely — that's
+ * the point: scroll the playfield all you want, the HUD strip stays put.
+ * Classic placements: a bottom status bar (this game: WY=128 → the last
+ * 16 pixel rows) or a full-width top bar. It CANNOT be a floating box —
+ * the window always runs to the screen's bottom-right corner.
+ *
+ * Gotchas:
+ *  - WX is offset by 7: WX=7 is the left edge. WX<7 glitches on hardware.
+ *  - The window has its OWN line counter: it renders ITS map from window
+ *    row 0 downward, regardless of WY — our HUD lives at $9C00 rows 0-1.
+ *  - On CGB the window cells take bank-1 attributes exactly like the BG
+ *    (set_wcell writes both banks).
+ *  - This block is DMG-era hardware — it transplants to plain GB examples
+ *    unchanged; only the bank-1 attribute half is CGB-specific.
+ *
+ * Window HUD layout (window map rows 0-1):
+ *   row 0:  SC dddddd  HI dddddd      row 1:  LV dd
+ * Static labels drawn once at transitions; the digits go through the
+ * vblank queue (see redraw_collect) so in-game updates never tear. */
+#define WINY      128                  /* screen y where the strip starts */
+#define HUD_SC_X  3                    /* score digits, window row 0 */
+#define HUD_HI_X  13                   /* hi-score digits, window row 0 */
+#define HUD_LV_X  3                    /* level digits, window row 1 */
+
+/* paint the whole window strip: dark backdrop + labels (LCD off only) */
+static void draw_window_static(void) {
+    uint8_t x, y;
+    for (y = 0; y < 2; y++)
+        for (x = 0; x < 20; x++) set_wcell(x, y, T_BLANK, PAL_OUT);
+    draw_wtext(0, 0, "SC");
+    draw_wtext(10, 0, "HI");
+    draw_wtext(0, 1, "LV");
+}
+
+/* draw every dynamic HUD value directly (LCD off / transitions only —
+ * in-game updates go through the queue, 4 cells per vblank) */
+static void draw_hud_now(void) {
     uint8_t i;
-    for (i = 0; i < 6; i++) set_cell((uint8_t)(HUD_X + i), 2, FONT_BASE + score_d[i], PAL_OUT);
-    set_cell(HUD_X, 5, FONT_BASE + (uint8_t)(level / 10), PAL_OUT);
-    set_cell((uint8_t)(HUD_X + 1), 5, FONT_BASE + (uint8_t)(level % 10), PAL_OUT);
-    /* NEXT gems are sprites now (update_sprites) — nothing to draw here */
+    for (i = 0; i < 6; i++) {
+        set_wcell((uint8_t)(HUD_SC_X + i), 0, FONT_BASE + score_d[i], PAL_OUT);
+        set_wcell((uint8_t)(HUD_HI_X + i), 0, FONT_BASE + hi_d[i], PAL_OUT);
+    }
+    set_wcell(HUD_LV_X, 1, FONT_BASE + (uint8_t)(level / 10), PAL_OUT);
+    set_wcell((uint8_t)(HUD_LV_X + 1), 1, FONT_BASE + (uint8_t)(level % 10), PAL_OUT);
 }
 
-/* Lay down the unchanging screen: clear the whole map, draw the well's left/
- * right/bottom walls, and the static HUD labels.  Only called with the LCD off
- * (it writes the entire map at once). */
+/* Lay down the unchanging screen: clear the whole BG map, draw the well's
+ * walls + floor, the right panel, and the window HUD.  Only called with the
+ * LCD off (it writes entire maps at once). */
 static void draw_static(void) {
     uint8_t x, y;
     uint16_t off;
@@ -638,15 +845,12 @@ static void draw_static(void) {
     }
     for (x = (uint8_t)(WELL_MX - 1); x <= (uint8_t)(WELL_MX + COLS); x++)
         set_cell(x, (uint8_t)(WELL_MY + ROWS), T_WALL, PAL_WELL);
-    /* static HUD labels (drawn once — the values come from draw_hud) */
-    draw_text(HUD_X, 1, "SCORE");
-    draw_text(HUD_X, 4, "LEVEL");
-    draw_text(HUD_X, 7, "NEXT");
+    draw_window_static();
 }
 
-/* Full LOCKED-well redraw (no piece — that's a sprite).  Used only with the
- * LCD OFF (boot / title↔game transitions), where writing all changed cells
- * at once is safe. */
+/* Full LOCKED-well repaint from the grid (no piece — that's a sprite).  Used
+ * only with the LCD OFF (boot / title↔game transitions), where writing all
+ * changed cells at once is safe. */
 static void redraw_all(void) {
     uint8_t r, c, col;
     uint8_t i = 0;
@@ -667,19 +871,26 @@ static void redraw_all(void) {
     }
 }
 
-/* ── deferred well/HUD rendering (NO LCD toggling in-game) ───────────
+/* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+ * Deferred well/HUD rendering — the vblank COLLECT/FLUSH queue.
+ * requires: update_sprites + redraw_flush as the FIRST two things after
+ *   wait_vblank (in that order), batches capped at REDRAW_BUDGET, and no
+ *   LCDC bit-7 toggling in-game.
+ *
  * This core blanks the whole frame on ANY LCDC bit-7 toggle (a strobe we
  * must never do), AND it occasionally drops a VRAM write even at the start
  * of vblank.  So in-game we never touch the LCD; instead:
- *   COLLECT — queue work (RAM only): changed cells after a lock, the HUD,
- *             and — when idle — a rolling SCRUB of the whole well.
+ *   COLLECT — queue work (RAM only): changed cells after a lock, the HUD
+ *             digits, and — when idle — a rolling SCRUB of the whole well.
  *   FLUSH   — write the queue to VRAM as the FIRST thing after wait_vblank.
  * The scrub re-writes every well cell from the grid every ~0.2s, so any
  * dropped write self-corrects instead of becoming a permanent wrong color
- * (the "3 oranges that won't clear" bug).  Idempotent ⇒ invisible. */
-/* Batches are kept small so the whole flush fits in vblank AFTER the OAM DMA
- * — overrunning into active display drops writes (a garbage "burst" on lock
- * frames before the scrub heals them). */
+ * (the "3 oranges that won't clear" bug).  Idempotent ⇒ invisible.
+ * Batches are kept small so the whole flush fits in vblank AFTER the OAM
+ * DMA — overrunning into active display drops writes (a garbage "burst" on
+ * lock frames before the scrub heals them).
+ * Queue offsets are plain offsets from $9800, so the same queue serves the
+ * BG map (well) and the window map at $9800+$400 (HUD digits). */
 #define REDRAW_BUDGET 4             /* changed well cells per frame (responsive) */
 #define SCRUB_N       4             /* idle cells re-written per frame (self-heal) */
 #define WQ_MAX        6             /* queue capacity (≤4 pushed per frame) */
@@ -711,9 +922,14 @@ static void wq_text(uint8_t col, uint8_t row, const char *s) {
         wq_push((uint16_t)row * 32 + col + i, font_slot(s[i]), PAL_OUT);
 }
 
+/* queue one window-HUD digit cell (window map = offset $400) */
+static void wq_wdigit(uint8_t col, uint8_t row, uint8_t digit) {
+    wq_push(WIN_OFF + (uint16_t)row * 32 + col, FONT_BASE + digit, PAL_OUT);
+}
+
 /* Fill the queue with the next batch of pending changes (RAM only).
  * Each branch pushes at most REDRAW_BUDGET cells, so the flush always fits
- * in vblank; the HUD and game-over text are split across two frames. */
+ * in vblank; the HUD digits and game-over text are split across frames. */
 static void redraw_collect(void) {
     uint8_t col, k, r, c, i;
     wq_n = 0;
@@ -733,14 +949,20 @@ static void redraw_collect(void) {
         if (scan_i >= NCELL) { scanning = 0; hud_pending = 1; hud_phase = 0; }
     } else if (hud_pending) {
         if (hud_phase == 0) {                       /* score digits 0-3 */
-            for (i = 0; i < 4; i++)
-                wq_push((uint16_t)2 * 32 + HUD_X + i, FONT_BASE + score_d[i], PAL_OUT);
+            for (i = 0; i < 4; i++) wq_wdigit((uint8_t)(HUD_SC_X + i), 0, score_d[i]);
             hud_phase = 1;
-        } else {                                    /* score digits 4-5 + level */
-            wq_push((uint16_t)2 * 32 + HUD_X + 4, FONT_BASE + score_d[4], PAL_OUT);
-            wq_push((uint16_t)2 * 32 + HUD_X + 5, FONT_BASE + score_d[5], PAL_OUT);
-            wq_push((uint16_t)5 * 32 + HUD_X,     FONT_BASE + (uint8_t)(level / 10), PAL_OUT);
-            wq_push((uint16_t)5 * 32 + HUD_X + 1, FONT_BASE + (uint8_t)(level % 10), PAL_OUT);
+        } else if (hud_phase == 1) {                /* score 4-5 + level */
+            wq_wdigit(HUD_SC_X + 4, 0, score_d[4]);
+            wq_wdigit(HUD_SC_X + 5, 0, score_d[5]);
+            wq_wdigit(HUD_LV_X, 1, (uint8_t)(level / 10));
+            wq_wdigit(HUD_LV_X + 1, 1, (uint8_t)(level % 10));
+            hud_phase = 2;
+        } else if (hud_phase == 2) {                /* hi-score digits 0-3 */
+            for (i = 0; i < 4; i++) wq_wdigit((uint8_t)(HUD_HI_X + i), 0, hi_d[i]);
+            hud_phase = 3;
+        } else {                                    /* hi-score digits 4-5 */
+            wq_wdigit(HUD_HI_X + 4, 0, hi_d[4]);
+            wq_wdigit(HUD_HI_X + 5, 0, hi_d[5]);
             hud_pending = 0;
             if (state == ST_OVER) { over_pending = 1; over_phase = 0; }
         }
@@ -762,9 +984,11 @@ static void redraw_collect(void) {
     }
 }
 
-/* Write the queued cells to VRAM.  MUST run first after wait_vblank, and
- * MUST finish inside the ~10-line vblank window or writes drop.  Pointer-walk
- * (not array indexing) — SDCC sm83 generates far tighter code for *p++. */
+/* Write the queued cells to VRAM.  MUST run first after wait_vblank (right
+ * after the OAM DMA), and MUST finish inside the ~10-line vblank window or
+ * writes drop.  Pointer-walk (not array indexing) — SDCC sm83 generates far
+ * tighter code for *p++.  Each cell is the bank pair: tile (VBK=0) then
+ * attribute (VBK=1) at the same offset — see the per-tile color idiom. */
 static void redraw_flush(void) {
     uint8_t k = wq_n;
     uint16_t *op;
@@ -782,15 +1006,17 @@ static void redraw_flush(void) {
     wq_n = 0;
 }
 
-/* a jagged, colorful gem pile to dress up the empty well on the title */
-static const uint8_t title_heights[COLS] = { 5, 7, 4, 8, 6, 7, 5, 6 };
+/* ── GAME LOGIC (clay — reshape freely) ── title screen.
+ * A jagged pile of all six gem colors dresses the well — it doubles as the
+ * "this cart is COLOR" proof the moment the title appears. */
+static const uint8_t title_heights[COLS] = { 4, 6, 3, 7, 5, 6, 4, 5 };
 
 static void draw_title(void) {
     uint8_t x, y, c, k, color;
-    /* clear the right panel (overwrites the HUD labels from draw_static) */
-    for (y = 0; y <= 17; y++)
+    /* clear the right panel (NEXT label from a previous game) */
+    for (y = 0; y <= 15; y++)
         for (x = 10; x <= 19; x++) set_cell(x, y, T_EMPTY, PAL_OUT);
-    /* decorative gems piled at the bottom of the well */
+    /* decorative gems piled at the bottom of the well, cycling palettes */
     color = 1;
     for (c = 0; c < COLS; c++) {
         for (k = 0; k < title_heights[c]; k++) {
@@ -800,20 +1026,23 @@ static void draw_title(void) {
             color++; if (color > NCOLORS) color = 1;
         }
     }
-    /* title text, aligned to the in-game HUD column */
-    draw_text(HUD_X, 2, "PUZZLE");
-    draw_text(HUD_X, 9, "PRESS");
-    draw_text(HUD_X, 10, "START");
+    /* game name + prompt, centered across the full 20-column screen */
+    draw_text((uint8_t)((20 - (sizeof(GAME_TITLE) - 1)) / 2), 2, GAME_TITLE);
+    draw_text(4, 4, "PRESS START");
 }
 
-/* LCD off / on — only used to bracket the full-screen rebuilds at the title and
- * game-start transitions.  NEVER call these from the in-game loop (the off-frame
- * blanks the whole screen — a flash/strobe). */
+/* LCD off / on — only used to bracket the full-screen rebuilds at the title
+ * and game-start transitions.  NEVER call these from the in-game loop (the
+ * off-frame blanks the whole screen — a flash/strobe).  blit_on enables BG +
+ * OBJ + the WINDOW (map $9C00) — see the window idiom for the LCDC bits. */
 static void blit_off(void) { wait_vblank(); LCDC = 0; }
-static void blit_on(void)  { LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO; }
+static void blit_on(void)  {
+    LCDC = LCDC_LCD_ON | LCDC_BG_ON | LCDC_OBJ_ON | LCDC_TILE_DATA_LO
+         | LCDC_WINDOW_ON | LCDC_WINDOW_MAP_HI;
+}
 
 /* zero the board and all run stats for a fresh game (shadow set to 0xFF so the
- * first redraw repaints every cell).  Does not touch music_on. */
+ * first redraw repaints every cell).  Does not touch music_on or hi_d. */
 static void reset_state(void) {
     uint8_t i;
     for (i = 0; i < NCELL; i++) grid[i] = 0;
@@ -837,13 +1066,14 @@ static void start_game(void) {
     blit_off();
     draw_static();
     redraw_all();
-    draw_hud();
+    draw_text(HUD_X, 1, "NEXT");
+    draw_hud_now();
     blit_on();
     update_sprites();
     scanning = 0; hud_pending = 0; over_pending = 0; wq_n = 0;
 }
 
-/* show the title screen (decorative gem pile + PUZZLE / PRESS START) */
+/* show the title screen (gem pile + name + PRESS START + persisted HI) */
 static void go_title(void) {
     reset_state();
     piece_active = 0;
@@ -852,22 +1082,44 @@ static void go_title(void) {
     draw_static();
     redraw_all();
     draw_title();
+    draw_hud_now();
     next_dirty = 1;
     blit_on();
     update_sprites();
     scanning = 0; hud_pending = 0; over_pending = 0; wq_n = 0;
 }
 
+/* the run is over: persist a new record, then let the queue paint GAME OVER
+ * + the updated HI digits (hud_pending → over_pending chain). */
+static void game_over(void) {
+    piece_active = 0;
+    state = ST_OVER;
+    sfx_over();
+    if (score_beats_hi()) {
+        uint8_t i;
+        for (i = 0; i < 6; i++) hi_d[i] = score_d[i];
+        hiscore_save();          /* battery SRAM — survives power-off */
+    }
+}
+
 void main(void) {
     uint8_t pad, prev = 0, t, rate, g;
 
-    /* one-time hardware setup: LCD defaults, vblank IRQ (so wait_vblank HALTs),
-     * the APU, then LCD off while we populate VRAM. */
+    /* ── HARDWARE IDIOM (load-bearing — reshape gameplay around this; see TROUBLESHOOTING) ──
+     * Boot order: LCD defaults (installs the OAM-DMA HRAM stub) → vblank IRQ
+     * (so wait_vblank HALTs instead of busy-polling LY — the poll runs at
+     * ~1/30 speed on this core) → APU on → LCD OFF → then all the bulk VRAM
+     * work (tiles, palettes, maps).  Tile/palette/map uploads REQUIRE a
+     * VRAM-safe window and boot does them all at once, so LCD-off is the
+     * only sane choice here.  The window position registers are plain I/O —
+     * set once, they hold. */
     lcd_init_default();
     enable_vblank_irq();
     sound_init();
     music_on = 1;          /* background music on by default (SELECT toggles) */
     LCDC = 0;
+    WY = WINY;             /* window HUD strip: bottom 16 pixel rows */
+    WX = 7;                /* WX is offset by 7 — this is the left edge */
 
     upload_tile(T_EMPTY, tile_empty);
     upload_tile(T_GEM,   tile_gem);
@@ -883,6 +1135,7 @@ void main(void) {
     load_obj_palettes();
     oam_clear();
 
+    hiscore_load();        /* battery SRAM — 0 on a fresh cart */
     go_title();
 
     /* Main loop, one pass per frame.  The order is deliberate: the two VRAM/OAM
@@ -902,8 +1155,11 @@ void main(void) {
         if ((pad & PAD_SELECT) && !(prev & PAD_SELECT)) music_toggle();
 
         if (state == ST_TITLE) {
+            /* ── GAME LOGIC (clay — reshape freely) ── press-start title
+             * (handheld: no 2P mode select — see the header note) */
             if ((pad & PAD_START) && !(prev & PAD_START)) start_game();
         } else if (state == ST_PLAY) {
+            /* ── GAME LOGIC (clay — reshape freely) ── one frame of play */
             if ((pad & PAD_LEFT) && !(prev & PAD_LEFT)
                 && !collides((uint8_t)(piece_x - 1), piece_y)) { piece_x--; sfx_move(); }
             if ((pad & PAD_RIGHT) && !(prev & PAD_RIGHT)
@@ -921,25 +1177,23 @@ void main(void) {
                 sfx_drop();
                 lock_and_resolve();
                 spawn();
-                if (state == ST_OVER) sfx_over();
                 start_redraw();
             }
 
             rate = (pad & PAD_DOWN) ? 3 : cur_fall_rate;
-            if (++fall_timer >= rate) {
+            if (state == ST_PLAY && ++fall_timer >= rate) {
                 fall_timer = 0;
                 if (collides(piece_x, (uint8_t)(piece_y + 1))) {
                     sfx_drop();
                     lock_and_resolve();
                     spawn();
-                    if (state == ST_OVER) sfx_over();
                     start_redraw();
                 } else {
                     piece_y++;
                 }
             }
-        } else { /* ST_OVER — START restarts immediately */
-            if ((pad & PAD_START) && !(prev & PAD_START)) start_game();
+        } else { /* ST_OVER — START returns to the title (shows the new HI) */
+            if ((pad & PAD_START) && !(prev & PAD_START)) go_title();
         }
 
         redraw_collect();   /* queue next frame's VRAM writes (RAM only) */