romdevtools 0.13.0 → 0.15.0

package/examples/gb/main.c

@@ -1,7 +1,7 @@
 /* ── Hello, Game Boy in C — SDCC sm83 port ─────────────────────────
  * Minimal: cycle the BG palette on every vblank.
  *
- * Build: buildSource({ platform: "gb", source: <this file>, language: "c" })
+ * Build: build({ output: "rom",  platform: "gb", source: <this file>, language: "c" })
  *
  * SDCC 4.4.0 codegen quirks to avoid in `__sfr __at` register-heavy
  * code:

package/examples/gb/templates/puzzle.c

@@ -118,7 +118,7 @@ static void lock_piece(void) {
                 grid[r][c]     = 0;
                 grid[r][c + 1] = 0;
                 grid[r][c + 2] = 0;
-                if (score < 65500) score += 30;
+                if (score < 65500u) score += 30;
             }
         }
     }

package/examples/gb/templates/racing.c

@@ -153,6 +153,6 @@ void main(void) {
         break;
       }
     }
-    if (score < 65500) score++;
+    if (score < 65500u) score++;
   }
 }

package/examples/gb/templates/shmup.c

@@ -162,7 +162,7 @@ void main(void) {
                 if (aabb(&bullets[i], &enemies[j])) {
                     bullets[i].alive = 0;
                     enemies[j].alive = 0;
-                    if (score < 65500) score += 10;
+                    if (score < 65500u) score += 10;
                     sound_play_noise(6);
                     break;
                 }

package/examples/gba/templates/gba_hello.c

@@ -5,7 +5,7 @@
  * pixel that moves left/right via the d-pad.
  *
  * Build via romdev:
- *   buildSource({platform:"gba", language:"c", runtime:"libgba",
+ *   build({ output: "rom", platform:"gba", language:"c", runtime:"libgba",
  *                source: <this file>})
  *
  * NOTE: the DEFAULT GBA runtime is libtonc (use `tonc_hello.c` instead

package/examples/gba/templates/maxmod_demo.c

@@ -10,7 +10,7 @@
  *   4. mmStart(MOD_<NAME>_FROM_HEADER, mode) to begin playback.
  *
  * Build via romdev:
- *   buildSource({
+ *   build({ output: "rom", 
  *     platform: "gba",
  *     language: "c",
  *     source:   <this file>,

package/examples/gba/templates/puzzle.c

@@ -22,6 +22,20 @@
 #include <tonc.h>
 #include "gba_sfx.h"
 
+/* draw a 5-digit score WITHOUT tte_printf (broken in this libtonc — GBA-1). */
+static void draw_score(int x, unsigned v) {
+    char buf[24];
+    int i, n = 0;
+    buf[n++]='#'; buf[n++]='{'; buf[n++]='P'; buf[n++]=':';
+    if (x >= 100) buf[n++] = '0' + (x/100)%10;
+    if (x >= 10)  buf[n++] = '0' + (x/10)%10;
+    buf[n++] = '0' + x%10;
+    buf[n++]=','; buf[n++]='8'; buf[n++]='}';
+    for (i = 4; i >= 0; i--) { buf[n+i] = '0' + (v % 10); v /= 10; }
+    n += 5; buf[n] = 0;
+    tte_write(buf);
+}
+
 #define COLS 6
 #define ROWS 12
 
@@ -134,7 +148,7 @@ static void lock_piece(void) {
                 grid[r][c]     = 0;
                 grid[r][c + 1] = 0;
                 grid[r][c + 2] = 0;
-                if (score < 65500) score += 30;
+                if (score < 65500u) score += 30;
                 sfx_tone(1, 1700, 10);  /* triple-clear chime */
             }
         }
@@ -211,7 +225,7 @@ int main(void) {
             new_piece();
             prev = now;
             tte_erase_rect(88 + 6*8, 8, 88 + 11*8, 16);
-            tte_printf("#{P:%d,8}%05d", 88 + 6*8, score);
+            draw_score(88 + 6*8, score);
             continue;
         }
         prev = now;
@@ -231,7 +245,7 @@ int main(void) {
         draw_piece(piece_x, piece_y, 0);
 
         tte_erase_rect(88 + 6*8, 8, 88 + 11*8, 16);
-        tte_printf("#{P:%d,8}%05d", 88 + 6*8, score);
+        draw_score(88 + 6*8, score);
     }
     return 0;
 }

package/examples/gba/templates/racing.c

@@ -15,6 +15,20 @@
 #include <tonc.h>
 #include "gba_sfx.h"
 
+/* draw a 5-digit score WITHOUT tte_printf (broken in this libtonc — GBA-1). */
+static void draw_score(int x, unsigned v) {
+    char buf[24];
+    int i, n = 0;
+    buf[n++]='#'; buf[n++]='{'; buf[n++]='P'; buf[n++]=':';
+    if (x >= 100) buf[n++] = '0' + (x/100)%10;
+    if (x >= 10)  buf[n++] = '0' + (x/10)%10;
+    buf[n++] = '0' + x%10;
+    buf[n++]=','; buf[n++]='8'; buf[n++]='}';
+    for (i = 4; i >= 0; i--) { buf[n+i] = '0' + (v % 10); v /= 10; }
+    n += 5; buf[n] = 0;
+    tte_write(buf);
+}
+
 #define LANE_LEFT_X    56
 #define LANE_MID_X    116
 #define LANE_RIGHT_X  176
@@ -149,7 +163,7 @@ int main(void) {
                 }
             }
 
-            if (score < 65500) score++;
+            if (score < 65500u) score++;
         }
 
         /* Sprite slots: 0 = player, 1..4 = obstacles. */
@@ -169,7 +183,7 @@ int main(void) {
         oam_copy(oam_mem, obj_buffer, 1 + MAX_OBSTACLES);
 
         tte_erase_rect(160 + 6*8, 8, 160 + 11*8, 16);
-        tte_printf("#{P:%d,8}%05d", 160 + 6*8, score);
+        draw_score(160 + 6*8, score);
     }
     return 0;
 }

package/examples/gba/templates/shmup.c

@@ -29,6 +29,26 @@
 #define TILE_BULLET 2
 #define TILE_ENEMY  3
 
+/* Draw a 5-digit score at pixel (x,8) WITHOUT tte_printf. The bundled libtonc's
+ * tte_printf with a %d/%05d conversion is broken (it routes through a vsnprintf
+ * path that isn't wired in this build — it garbles the output AND wedges the
+ * game loop when called per-frame, GBA-1). We build the string ourselves and
+ * use tte_write, which processes the #{P:x,y} position command but does NO
+ * format conversion → safe every frame. */
+static void draw_score(int x, unsigned v) {
+    char buf[24];
+    int i, n = 0;
+    /* "#{P:<x>,8}" position command, then 5 decimal digits. */
+    buf[n++]='#'; buf[n++]='{'; buf[n++]='P'; buf[n++]=':';
+    if (x >= 100) buf[n++] = '0' + (x/100)%10;
+    if (x >= 10)  buf[n++] = '0' + (x/10)%10;
+    buf[n++] = '0' + x%10;
+    buf[n++]=','; buf[n++]='8'; buf[n++]='}';
+    for (i = 4; i >= 0; i--) { buf[n+i] = '0' + (v % 10); v /= 10; }
+    n += 5; buf[n] = 0;
+    tte_write(buf);
+}
+
 /* 4bpp tiles (8 rows × 32 bits each = 32 bytes). Each nibble is a
  * palette index. Index 0 = transparent. */
 static const u32 tile_ship[8] = {
@@ -153,7 +173,7 @@ int main(void) {
                 if (aabb_hit(&bullets[i], &enemies[j])) {
                     bullets[i].alive = 0;
                     enemies[j].alive = 0;
-                    if (score < 65500) score += 10;
+                    if (score < 65500u) score += 10;
                     sfx_noise(6);   /* explosion */
                     break;
                 }
@@ -188,10 +208,9 @@ int main(void) {
 
         oam_copy(oam_mem, obj_buffer, 128);
 
-        /* Score: 5-digit ASCII via TTE printf. Tte handles VRAM tile
-         * writes — safe to call once per frame. */
+        /* Score: 5 digits via draw_score (NOT tte_printf — see GBA-1). */
         tte_erase_rect(8 + 6*8, 8, 8 + 11*8, 16);
-        tte_printf("#{P:%d,8}%05d", 8 + 6*8, score);
+        draw_score(8 + 6*8, score);
     }
     return 0;
 }

package/examples/gba/templates/tonc_hello.c

@@ -5,7 +5,7 @@
  * canonical "Hello GBA" pattern from gbadev.net/tonc.
  *
  * Build via romdev:
- *   buildSource({platform:"gba", language:"c", source: <this file>})
+ *   build({ output: "rom", platform:"gba", language:"c", source: <this file>})
  *
  * (defaults to runtime:"libtonc" — pass {runtime:"libgba"} to use
  *  devkitPro's libgba instead, or {runtime:"none"} for bare gcc.)
@@ -59,9 +59,11 @@ int main(void) {
     tte_write("Hello, Tonc!\n");
     tte_write("Built with romdev\n");
 
-    /* Formatted output without needing iprintf or libsysbase. */
-    int year = 2026;
-    tte_printf("#{P:32,80}Year: %d\n", year);
+    /* NOTE: tte_printf with a %d/%05d conversion is broken in this libtonc
+     * build (it garbles output + can wedge the loop — GBA-1). For dynamic
+     * numbers, build the string yourself and tte_write it (see the genre
+     * scaffolds' draw_score). For static text just tte_write a literal: */
+    tte_write("#{P:32,80}Year: 2026\n");
 
     /* Game loop. VBlankIntrWait() halts the CPU until next vblank —
      * saves battery on real hardware. */

package/examples/gbc/main.asm

@@ -7,7 +7,7 @@
 ;   - palette 0 entry 0 = backdrop (blue here), entry 1 = yellow
 ;
 ; Build with:
-;   buildSource({platform:"gbc", source: <this>})
+;   build({ output: "rom", platform:"gbc", source: <this>})
 ;
 ; rgbfix is invoked automatically to fix the header checksums.
 

package/examples/gbc/templates/puzzle.c

@@ -118,7 +118,7 @@ static void lock_piece(void) {
                 grid[r][c]     = 0;
                 grid[r][c + 1] = 0;
                 grid[r][c + 2] = 0;
-                if (score < 65500) score += 30;
+                if (score < 65500u) score += 30;
             }
         }
     }

package/examples/gbc/templates/racing.c

@@ -159,6 +159,6 @@ void main(void) {
         break;
       }
     }
-    if (score < 65500) score++;
+    if (score < 65500u) score++;
   }
 }

package/examples/gbc/templates/shmup.c

@@ -178,7 +178,7 @@ void main(void) {
                 if (aabb(&bullets[i], &enemies[j])) {
                     bullets[i].alive = 0;
                     enemies[j].alive = 0;
-                    if (score < 65500) score += 10;
+                    if (score < 65500u) score += 10;
                     sound_play_noise(6);
                     break;
                 }

package/examples/genesis/main.s

@@ -10,7 +10,7 @@
 ;   7. Enable display and park forever.
 ;
 ; BUILD:
-;   buildSource({ platform: "genesis", source: /* this file */ });
+;   build({ output: "rom",  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.

package/examples/genesis/templates/puzzle.c

@@ -137,7 +137,7 @@ static void lock_piece(void) {
                 grid[r][c]     = 0;
                 grid[r][c + 1] = 0;
                 grid[r][c + 2] = 0;
-                if (score < 65500) score += 30;
+                if (score < 65500u) score += 30;
                 sfx_tone(0, 250, 12);  /* triple-clear chime */
             }
         }

package/examples/genesis/templates/racing.c

@@ -27,6 +27,8 @@
 
 #define T_CAR_P1   (TILE_USER_INDEX + 0)
 #define T_CAR_EN   (TILE_USER_INDEX + 1)
+#define T_LANE     (TILE_USER_INDEX + 2)   /* dashed lane divider (BG_B) */
+#define T_EDGE     (TILE_USER_INDEX + 3)   /* solid road edge      (BG_B) */
 
 static const u32 tile_car_p1[8] = {
     0x01111110, 0x11111111, 0x12222221, 0x11111111,
@@ -36,6 +38,40 @@ static const u32 tile_car_enemy[8] = {
     0x03333330, 0x33333333, 0x34444443, 0x33333333,
     0x33333333, 0x34444443, 0x33333333, 0x03300330,
 };
+/* Dashed lane-divider segment (colour 2 = grey): a 2px dash in the
+ * centre columns, on/off vertically so a stacked column reads as a
+ * dashed road centre-line. */
+static const u32 tile_lane[8] = {
+    0x00022000, 0x00022000, 0x00022000, 0x00000000,
+    0x00000000, 0x00022000, 0x00022000, 0x00022000,
+};
+/* Solid 2px road-edge stripe (colour 2 = grey) down the right side of
+ * the tile — used on the left rail; mirrored (hflip) for the right. */
+static const u32 tile_edge[8] = {
+    0x00000022, 0x00000022, 0x00000022, 0x00000022,
+    0x00000022, 0x00000022, 0x00000022, 0x00000022,
+};
+
+/* The road lives on BG_B (8×8 cells). Two dashed dividers sit between the
+ * three lanes; solid edges frame the outermost lanes. */
+#define ROAD_TOP_ROW   1
+#define ROAD_BOT_ROW   26
+#define LANE_DIV1_COL  ((LANE_LEFT_X + 8 + LANE_MID_X)  / 16)
+#define LANE_DIV2_COL  ((LANE_MID_X  + 8 + LANE_RIGHT_X) / 16)
+#define ROAD_EDGE_L    ((LANE_LEFT_X  - 12) / 8)
+#define ROAD_EDGE_R    ((LANE_RIGHT_X + 12) / 8)
+
+static void draw_road(void) {
+    s16 r;
+    for (r = ROAD_TOP_ROW; r <= ROAD_BOT_ROW; r++) {
+        /* Left edge (stripe on its right), right edge (hflipped). */
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_EDGE), ROAD_EDGE_L, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 1, T_EDGE), ROAD_EDGE_R, r);
+        /* Two dashed lane dividers. */
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_LANE), LANE_DIV1_COL, r);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_LANE), LANE_DIV2_COL, r);
+    }
+}
 
 typedef struct { s16 x, y; bool alive; } Car;
 
@@ -97,6 +133,11 @@ int main(bool hard) {
 
     VDP_loadTileData(tile_car_p1,    T_CAR_P1, 1, DMA);
     VDP_loadTileData(tile_car_enemy, T_CAR_EN, 1, DMA);
+    VDP_loadTileData(tile_lane,      T_LANE,   1, DMA);
+    VDP_loadTileData(tile_edge,      T_EDGE,   1, DMA);
+
+    /* Draw the static road (edges + dashed lane dividers) once on BG_B. */
+    draw_road();
 
     VDP_drawText("SCORE", 28, 2);
     VDP_drawText("L/R MOVES LANE", 13, 27);
@@ -149,7 +190,7 @@ int main(bool hard) {
                 }
             }
 
-            if (score < 65500) score++;
+            if (score < 65500u) score++;
         }
 
         /* SAT update — player + up to 4 obstacles = 5 sprites. */
@@ -160,6 +201,9 @@ int main(bool hard) {
             VDP_setSprite(slot++, obstacles[i].x, ey, SPRITE_SIZE(1, 1),
                           TILE_ATTR_FULL(PAL1, 1, 0, 0, T_CAR_EN));
         }
+        /* Link slots 0..slot-1 so the VDP's SAT walk draws all of them — without
+         * this the link bytes stay 0 (= end-of-list) and only slot 0 renders. */
+        VDP_linkSprites(0, slot);
         VDP_updateSprites(slot, DMA);
 
         render_score();

package/examples/genesis/templates/shmup.c

@@ -81,11 +81,15 @@ static void fire_bullet(void) {
     }
 }
 
+static u16 spawn_seed;  /* free-running, advances every spawn (NOT spawn_timer,
+                         * which is always 28 at the spawn call → one column) */
 static void spawn_enemy(void) {
     for (u16 i = 0; i < MAX_ENEMIES; i++) {
         if (!enemies[i].alive) {
-            /* Cheap deterministic-but-varying x — wraps every 7 spawns. */
-            enemies[i].x = ((spawn_timer * 37) & 0xFF) % (320 - 16) + 8;
+            /* Cheap LCG-ish spread across the playfield so enemies don't all
+             * descend in a single column. */
+            spawn_seed = (u16)(spawn_seed * 1103 + 12345);
+            enemies[i].x = (s16)((spawn_seed >> 4) % (320 - 16) + 8);
             enemies[i].y = -8;
             enemies[i].alive = TRUE;
             return;
@@ -157,7 +161,7 @@ int main(bool hard) {
                 if (aabb_hit(&bullets[i], &enemies[j])) {
                     bullets[i].alive = FALSE;
                     enemies[j].alive = FALSE;
-                    if (score < 65500) score += 10;
+                    if (score < 65500u) score += 10;
                     sfx_noise(8);   /* explosion */
                     break;
                 }
@@ -177,6 +181,11 @@ int main(bool hard) {
             VDP_setSprite(7 + i, enemies[i].x, ey, SPRITE_SIZE(1, 1),
                           TILE_ATTR_FULL(PAL2, 1, 0, 0, T_ENEMY));
         }
+        /* CHAIN the sprite linked list before uploading: VDP_setSprite does NOT
+         * set the link byte, and the SAT link bytes init to 0 (= "end of list"),
+         * so the VDP's sprite walk stops after slot 0 → only ONE sprite draws.
+         * VDP_linkSprites(0, N) links slots 0..N-1 so all N render. */
+        VDP_linkSprites(0, 1 + MAX_BULLETS + MAX_ENEMIES);
         VDP_updateSprites(1 + MAX_BULLETS + MAX_ENEMIES, DMA);
 
         render_score();

package/examples/genesis/templates/shmup_2p.c

@@ -196,7 +196,7 @@ int main(bool hard) {
                 if (p1_bullets[i].alive && aabb(&p1_bullets[i], &enemies[j])) {
                     p1_bullets[i].alive = FALSE;
                     enemies[j].alive = FALSE;
-                    if (score_p1 < 65500) score_p1 += 10;
+                    if (score_p1 < 65500u) score_p1 += 10;
                     sfx_noise(8);
                     break;
                 }
@@ -206,7 +206,7 @@ int main(bool hard) {
                 if (p2_bullets[i].alive && aabb(&p2_bullets[i], &enemies[j])) {
                     p2_bullets[i].alive = FALSE;
                     enemies[j].alive = FALSE;
-                    if (score_p2 < 65500) score_p2 += 10;
+                    if (score_p2 < 65500u) score_p2 += 10;
                     sfx_noise(8);
                     break;
                 }

package/examples/genesis/templates/sports.c

@@ -32,6 +32,8 @@
 
 #define T_PADDLE    (TILE_USER_INDEX + 0)
 #define T_BALL      (TILE_USER_INDEX + 1)
+#define T_RAIL      (TILE_USER_INDEX + 2)   /* solid court rail (BG_B) */
+#define T_NET       (TILE_USER_INDEX + 3)   /* dashed centre-line segment */
 
 /* 4bpp 8×8 tile, all colour 1 → solid white block. */
 static const u32 tile_solid[8] = {
@@ -39,6 +41,35 @@ static const u32 tile_solid[8] = {
     0x11111111, 0x11111111, 0x11111111, 0x11111111,
 };
 
+/* Centre-net segment: a 2px-wide vertical dash down the middle of an 8×8
+ * tile (colour 1 in the centre columns, transparent elsewhere). Stacked
+ * down the court's centre column it reads as a dashed Pong net. */
+static const u32 tile_net[8] = {
+    0x00011000, 0x00011000, 0x00011000, 0x00000000,
+    0x00011000, 0x00011000, 0x00011000, 0x00000000,
+};
+
+/* The court lives on BG_B (cells are 8×8): top + bottom rails plus a
+ * dashed centre net. 320px = 40 cols, COURT_TOP/BOT are pixel rows. */
+#define COURT_COL_L   (PADDLE_X1 / 8)
+#define COURT_COL_R   (PADDLE_X2 / 8)
+#define COURT_ROW_TOP (COURT_TOP / 8)
+#define COURT_ROW_BOT (COURT_BOT / 8 - 1)
+#define COURT_NET_COL (COURT_W / 16)
+
+static void draw_court(void) {
+    s16 c, r;
+    /* Top + bottom rails span the playfield width. */
+    for (c = COURT_COL_L; c <= COURT_COL_R; c++) {
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_RAIL), c, COURT_ROW_TOP);
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_RAIL), c, COURT_ROW_BOT);
+    }
+    /* Dashed centre net between the rails. */
+    for (r = COURT_ROW_TOP + 1; r < COURT_ROW_BOT; r++) {
+        VDP_setTileMapXY(BG_B, TILE_ATTR_FULL(PAL0, 0, 0, 0, T_NET), COURT_NET_COL, r);
+    }
+}
+
 static s16 p1y, p2y;       /* paddle top Y, pixels */
 static s16 bx, by;         /* ball top-left, pixels */
 static s16 bdx, bdy;
@@ -77,6 +108,11 @@ int main(bool hard) {
 
     VDP_loadTileData(tile_solid, T_PADDLE, 1, DMA);
     VDP_loadTileData(tile_solid, T_BALL,   1, DMA);
+    VDP_loadTileData(tile_solid, T_RAIL,   1, DMA);
+    VDP_loadTileData(tile_net,   T_NET,    1, DMA);
+
+    /* Draw the static court (rails + centre net) once on BG_B. */
+    draw_court();
 
     VDP_drawText("PLAYER 1", 2, 1);
     VDP_drawText("PLAYER 2", 28, 1);
@@ -161,6 +197,9 @@ int main(bool hard) {
         }
         VDP_setSprite(slot++, bx, by, SPRITE_SIZE(1, 1),
                       TILE_ATTR_FULL(PAL0, 1, 0, 0, T_BALL));
+        /* Link slots 0..slot-1 so the VDP's SAT walk draws all of them — without
+         * this the link bytes stay 0 (= end-of-list) and only slot 0 renders. */
+        VDP_linkSprites(0, slot);
         VDP_updateSprites(slot, DMA);
 
         render_scores();

package/examples/gg/templates/hello_sprite.c

@@ -1,21 +1,22 @@
-/* ── hello_sprite.c — SMS starter (one sprite + d-pad) ──────────────
+/* ── hello_sprite.c — Game Gear starter (one sprite + d-pad) ────────
  *
- * Drives one sprite around the SMS screen with the directional pad.
- * Uses the bundled SMS runtime helpers (gg_vdp_init, gg_load_tiles,
- * gg_load_palette, sms_sprite_*, gg_vblank_wait, gg_joypad_read).
+ * Drives one sprite around the Game Gear screen with the directional
+ * pad. Uses the bundled GG runtime helpers (gg_vdp_init, gg_load_tiles,
+ * gg_load_palette, gg_sprite_*, gg_vblank_wait, gg_joypad_read).
  *
- * SMS hardware notes the templates assume:
- *   - 256×192 visible area in mode 4
+ * GG hardware notes the templates assume:
+ *   - 256×192 internal frame; only the centered 160×144 region SHOWS.
+ *     Keep gameplay sprites inside [VIS_X0..VIS_X1] x [VIS_Y0..VIS_Y1].
  *   - Sprite attribute table at VRAM $3F00 (configured by gg_vdp_init)
- *   - Sprite tile data at VRAM $2000 (R6 = 0xFB)
+ *   - Sprite tile data at VRAM $2000 (R6 = 0xFF → SA13 set → $2000)
  *   - 64 sprite slots × 4 bytes (Y / X / tile / unused)
  *
  * Multi-file project — main.c plus the runtime .c files. Build with:
- *   buildSource({platform:"sms", language:"c",
+ *   build({ output: "rom", platform:"gg", language:"c",
  *                sources: { "main.c": ..., "vdp_init.c": ..., ... },
  *                includes: { "gg_hw.h": ... }})
  *
- * createProject({platform:"sms", template:"hello_sprite"}) copies all
+ * createProject({platform:"gg", template:"hello_sprite"}) copies all
  * the bits into your project tree.
  */
 #include "gg_hw.h"
@@ -34,16 +35,29 @@ extern void gg_sprite_init(void);
 extern void gg_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
 extern void gg_sat_upload(void);
 
-/* BG palette: backdrop blue + yellow. Sprite palette (entries 16-31)
- * we set white at index 17 so our sprite is visible.
- * SMS CRAM is 2-2-2 BGR: 0x00=black, 0x3F=white. */
-static const uint8_t palette[32] = {
-  0x10,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
-  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
-  0x00,0x3F,0x00,0x00, 0x00,0x00,0x00,0x00,
-  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+/* GG palette = 32 entries × 2 bytes (4-4-4 BGR LE): low=(g<<4)|r, high=b.
+ * Entries 0-15 = BG, 16-31 = SPRITE. gg_load_palette reads 64 bytes, so a
+ * 32-byte SMS-style array leaves the sprite palette (16-31) reading past the
+ * array = garbage = INVISIBLE sprites. Sprite colour index N uses entry 16+N,
+ * so sprite colour 1 = entry 17 (white here). */
+static const uint8_t palette[64] = {
+  /* BG 0-15: entry 0 = dark navy backdrop */
+  0x20,0x02, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* SPRITE 16-31: 16=transparent, 17=white */
+  0,0, 0xFF,0x0F, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
 };
 
+/* ── Game Gear visible viewport ──────────────────────────────────────
+ * Sprite OAM uses SMS HARDWARE coordinates (256x192 space), but the GG
+ * LCD only shows the CENTER 160x144. Keep the sprite inside this box or
+ * it's placed "correctly" in hardware yet INVISIBLE on screen. */
+#define VIS_X0  48
+#define VIS_Y0  24
+#define VIS_X1  207   /* 48 + 160 - 1 */
+#define VIS_Y1  167   /* 24 + 144 - 1 */
+
 /* One 8×8 sprite tile (4bpp interleaved). Filled square in color 1. */
 static const uint8_t sprite_tile[32] = {
   0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
@@ -53,8 +67,8 @@ static const uint8_t sprite_tile[32] = {
 };
 
 void main(void) {
-  uint8_t x = 124;   /* mid-screen X */
-  uint8_t y = 88;    /* mid-screen Y */
+  uint8_t x = (VIS_X0 + VIS_X1) / 2;   /* center of the visible window */
+  uint8_t y = (VIS_Y0 + VIS_Y1) / 2;
   uint8_t prev = 0;
 
   gg_vdp_init();
@@ -80,10 +94,11 @@ void main(void) {
     gg_sat_upload();
 
     pad = gg_joypad_read();
-    if (pad & JOY_LEFT  && x > 0)       x = (uint8_t)(x - 2);
-    if (pad & JOY_RIGHT && x < 248)     x = (uint8_t)(x + 2);
-    if (pad & JOY_UP    && y > 0)       y = (uint8_t)(y - 2);
-    if (pad & JOY_DOWN  && y < 184)     y = (uint8_t)(y + 2);
+    /* Clamp to the visible window so the sprite never slides off-screen. */
+    if (pad & JOY_LEFT  && x > VIS_X0)      x = (uint8_t)(x - 2);
+    if (pad & JOY_RIGHT && x < VIS_X1 - 8)  x = (uint8_t)(x + 2);
+    if (pad & JOY_UP    && y > VIS_Y0)      y = (uint8_t)(y - 2);
+    if (pad & JOY_DOWN  && y < VIS_Y1 - 8)  y = (uint8_t)(y + 2);
     prev = pad;
     (void)prev;
   } while (1);

package/examples/gg/templates/music_demo.c

@@ -36,14 +36,17 @@ extern void gg_sprite_init(void);
 extern void gg_sprite_set(uint8_t slot, uint8_t x, uint8_t y, uint8_t tile);
 extern void gg_sat_upload(void);
 
-/* Background = black. Sprite palette (entries 16+):
- *   16 = transparent backdrop, 17 = white, 18 = green, 19 = red.
- * CRAM bytes on SMS/GG are 2-2-2 BGR. */
-static const uint8_t palette[32] = {
-  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
-  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
-  0x00,0x3F,0x0C,0x03, 0x00,0x00,0x00,0x00,
-  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+/* GG palette = 32 entries × 2 bytes (4-4-4 BGR LE): low=(g<<4)|r, high=b.
+ * gg_load_palette reads 64 bytes; a 32-byte array leaves the sprite palette
+ * (entries 16-31) reading garbage = invisible sprites. Sprite palette:
+ *   16 = transparent, 17 = white, 18 = green, 19 = red. */
+static const uint8_t palette[64] = {
+  /* BG 0-15: entry 0 = dark navy backdrop */
+  0x20,0x02, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
+  /* SPRITE 16-31: 16=transparent, 17=white, 18=green, 19=red */
+  0,0, 0xFF,0x0F, 0xF0,0x00, 0x0F,0x00, 0,0, 0,0, 0,0, 0,0,
+  0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0, 0,0,
 };
 
 /* Three 8×8 sprite tiles, 4bpp interleaved (4 planes × 8 rows):