romdev-mcp 0.1.1

package/examples/gg/templates/tile_engine.c

@@ -0,0 +1,137 @@
+/* ── tile_engine.c — SMS tile-map starter ───────────────────────────
+ *
+ * 32×24 tile world drawn on the SMS BG plane with a walking player
+ * sprite + AABB collision against solid tile indices.
+ *
+ * SMS BG name table is at VRAM $3800 — 32 cells wide × 28 rows × 2
+ * bytes per cell. Only 24 rows are visible in mode 4. Each name-table
+ * entry packs: tile_index (10 bits across two bytes) + h/v flip +
+ * palette + priority.
+ */
+#include "gg_hw.h"
+#include "gg_sfx.h"
+#include <stdint.h>
+
+extern void gg_vdp_init(void);
+extern void gg_vdp_display_on(void);
+extern void gg_vdp_write_reg(uint8_t reg, uint8_t value);
+extern void gg_vdp_set_addr(uint16_t addr, uint8_t prefix);
+extern void gg_load_palette(const uint8_t *palette);
+extern void gg_load_tiles(uint16_t vram_dest, const uint8_t *src, uint16_t byte_count);
+extern void gg_set_tilemap_cell(uint8_t row, uint8_t col, uint8_t tile_idx, uint8_t attr);
+extern void gg_vblank_wait(void);
+extern uint8_t gg_joypad_read(void);
+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);
+
+#define WORLD_W 32
+#define WORLD_H 24
+
+#define T_OPEN  0
+#define T_WALL  1
+#define T_SPR   0   /* sprite tile uses sprite-tile-bank (R6=0xFB) */
+
+static const uint8_t palette[32] = {
+  /* BG palette: backdrop blue, wall colour 1 dark grey, colour 2 light grey */
+  0x10,0x14,0x2A,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+  /* Sprite palette: white at idx 1 */
+  0x00,0x3F,0x00,0x00, 0x00,0x00,0x00,0x00,
+  0x00,0x00,0x00,0x00, 0x00,0x00,0x00,0x00,
+};
+
+static const uint8_t bg_tiles[32 * 2] = {
+  /* T_OPEN — blank */
+  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,0,0,
+  /* T_WALL — bordered block */
+  0xFF,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
+  0x81,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
+  0x81,0x00,0x00,0x00, 0x81,0x00,0x00,0x00,
+  0x81,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+};
+
+static const uint8_t sprite_tile[32] = {
+  0x3C,0x00,0x00,0x00, 0x7E,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0xFF,0x00,0x00,0x00, 0xFF,0x00,0x00,0x00,
+  0x7E,0x00,0x00,0x00, 0x3C,0x00,0x00,0x00,
+};
+
+static uint8_t world[WORLD_H][WORLD_W];
+
+static void world_build(void) {
+  uint8_t y, x;
+  for (y = 0; y < WORLD_H; y++) {
+    for (x = 0; x < WORLD_W; x++) {
+      world[y][x] = (x == 0 || x == WORLD_W - 1
+                     || y == 0 || y == WORLD_H - 1) ? T_WALL : T_OPEN;
+    }
+  }
+  /* A few interior platforms. */
+  for (x = 4; x < 12; x++) world[10][x] = T_WALL;
+  for (x = 16; x < 24; x++) world[14][x] = T_WALL;
+  for (x = 6; x < 10; x++)  world[6][x]  = T_WALL;
+}
+
+static void world_draw(void) {
+  uint8_t y, x;
+  for (y = 0; y < WORLD_H; y++) {
+    for (x = 0; x < WORLD_W; x++) {
+      gg_set_tilemap_cell(y, x, world[y][x], 0);
+    }
+  }
+}
+
+static uint8_t solid_at(int16_t px, int16_t py) {
+  int16_t tx = px >> 3;
+  int16_t ty = py >> 3;
+  if (tx < 0 || tx >= WORLD_W || ty < 0 || ty >= WORLD_H) return 1;
+  return world[ty][tx] != T_OPEN;
+}
+
+void main(void) {
+  int16_t px = 16, py = 16;
+
+  gg_vdp_init();
+  gg_load_palette(palette);
+  /* BG tiles at VRAM $0000 (R4 = 0xFF). Two tiles = 64 bytes. */
+  gg_load_tiles(0x0000, bg_tiles, 64);
+  /* Sprite tile at VRAM $2000. */
+  gg_load_tiles(0x2000, sprite_tile, 32);
+
+  world_build();
+  world_draw();
+
+  gg_sprite_init();
+  sfx_init();
+  sfx_tone(0, 220, 12);
+  gg_sprite_set(0, (uint8_t)px, (uint8_t)py, 0);
+  gg_sat_upload();
+
+  gg_vdp_display_on();
+
+  do {
+    uint8_t pad;
+    int16_t nx, ny;
+    gg_vblank_wait();
+    sfx_update();
+    gg_sprite_set(0, (uint8_t)px, (uint8_t)py, 0);
+    gg_sat_upload();
+
+    pad = gg_joypad_read();
+    nx = px; ny = py;
+    if (pad & JOY_LEFT)  nx = (int16_t)(px - 1);
+    if (pad & JOY_RIGHT) nx = (int16_t)(px + 1);
+    if (pad & JOY_UP)    ny = (int16_t)(py - 1);
+    if (pad & JOY_DOWN)  ny = (int16_t)(py + 1);
+
+    if (!solid_at(nx, py) && !solid_at(nx + 7, py)
+        && !solid_at(nx, py + 7) && !solid_at(nx + 7, py + 7))
+      px = nx;
+    if (!solid_at(px, ny) && !solid_at(px + 7, ny)
+        && !solid_at(px, ny + 7) && !solid_at(px + 7, ny + 7))
+      py = ny;
+  } while (1);
+}

package/examples/lynx/main.c

@@ -0,0 +1,4 @@
+// Hello, Atari Lynx — minimal cc65 C program.
+void main(void) {
+  while (1) { }
+}

package/examples/lynx/templates/default.c

@@ -0,0 +1,41 @@
+/* ── default.c — minimal Atari Lynx starter ──────────────────────
+ *
+ * Boots TGI (cc65's graphics layer over Suzy's blitter), draws a
+ * color-cycling square + greeting. Smallest possible "ROM that does
+ * something visible" — use this as the starting point when you're
+ * not yet sure what you want to build.
+ *
+ * For something more game-shaped:
+ *   - hello_sprite — joystick-moved sprite
+ *   - shmup / platformer / puzzle / sports / racing — genre scaffolds
+ *   - music_demo   — cc65's lynx_snd_play streaming music engine
+ */
+
+#include <tgi.h>
+#include <lynx.h>
+
+void main(void) {
+  static const unsigned char palette[8] = {
+    COLOR_RED,    COLOR_YELLOW, COLOR_GREEN,     COLOR_LIGHTBLUE,
+    COLOR_BLUE,   COLOR_PURPLE, COLOR_LIGHTGREEN, COLOR_WHITE,
+  };
+  unsigned char shade = 0;
+  unsigned int  frame = 0;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+
+  for (;;) {
+    tgi_clear();
+    tgi_setcolor(palette[shade]);
+    tgi_bar(70, 40, 90, 62);
+    tgi_setcolor(COLOR_WHITE);
+    tgi_outtextxy(2, 2, "HELLO LYNX");
+    tgi_updatedisplay();
+
+    frame++;
+    if ((frame & 0x1F) == 0) {        /* every 32 frames */
+      shade = (shade + 1) & 0x07;
+    }
+  }
+}

package/examples/lynx/templates/hello_sprite.c

@@ -0,0 +1,39 @@
+// ── hello_sprite.c — Atari Lynx hello + joystick movement ────────────
+//
+// Uses cc65's TGI (Tiny Graphics Interface) which handles Suzy's
+// blitter for us. A single colored square moves under joystick control.
+//
+// Lynx joystick reading via cc65's joy_* API. We use the bundled
+// lynx_stdjoy driver.
+
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include "lynx_sfx.h"
+
+void main(void) {
+  unsigned char x = 80, y = 50;
+  unsigned char joy;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+  joy_install(&lynx_stdjoy_joy);
+  sfx_init();
+  sfx_tone(0, 80, 12);  /* boot chime */
+
+  for (;;) {
+    tgi_clear();
+    tgi_setcolor(COLOR_YELLOW);
+    tgi_bar(x, y, x + 8, y + 8);
+    tgi_setcolor(COLOR_WHITE);
+    tgi_outtextxy(2, 2, "HELLO LYNX");
+    tgi_updatedisplay();
+    sfx_update();
+
+    joy = joy_read(JOY_1);
+    if (JOY_LEFT(joy)  && x > 0)   x--;
+    if (JOY_RIGHT(joy) && x < 152) x++;
+    if (JOY_UP(joy)    && y > 12)  y--;
+    if (JOY_DOWN(joy)  && y < 94)  y++;
+  }
+}

package/examples/lynx/templates/music_demo.c

@@ -0,0 +1,37 @@
+// ── music_demo.c — cc65 lynx_snd_play music engine demo ─────────────
+//
+// Demonstrates the cc65 4-channel music driver on the Atari Lynx.
+// Unlike lynx_sfx (one-shot pokes to the MIKEY voice registers) the
+// snd_* API streams a bytestream of (note, length) tuples driven by a
+// 240Hz timer IRQ — the same primitive used by Lynx-tracker exports.
+//
+// Wiring:
+//   1) lynx_snd_init()                        — set up 240Hz IRQ, reset voices
+//   2) lynx_snd_play(0, demo_music)           — start streaming on channel 0
+//   3) main loop just keeps the screen alive; the IRQ does the audio work
+//
+// To stop / restart you can call lynx_snd_stop() or lynx_snd_play again
+// with the same data. The music data itself is in lynx_music.c (the
+// byte array IS the source — no asset pipeline involved).
+
+#include <tgi.h>
+#include <lynx.h>
+#include "lynx_music.h"
+
+void main(void) {
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+
+  lynx_snd_init();
+  lynx_snd_play(0, (unsigned char *)demo_music);
+
+  for (;;) {
+    tgi_clear();
+    tgi_setcolor(COLOR_WHITE);
+    tgi_outtextxy(20, 20, "LYNX MUSIC DEMO");
+    tgi_setcolor(COLOR_YELLOW);
+    tgi_outtextxy(20, 40, "channel 0 playing");
+    tgi_outtextxy(20, 50, "via lynx_snd_play");
+    tgi_updatedisplay();
+  }
+}

package/examples/lynx/templates/platformer.c

@@ -0,0 +1,72 @@
+// ── platformer.c — Atari Lynx single-screen platformer ──────────────
+//
+// Subpixel gravity + jump + land-on-top collision. Static platforms
+// drawn as rectangles each frame. cc65 tgi + lynx joystick.
+
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include <stdint.h>
+#include "lynx_sfx.h"
+
+typedef struct { int16_t x, y, w, h; } Rect;
+
+static const Rect platforms[] = {
+  {   0, 94, 160,  8 }, /* floor */
+  {  16, 76,  32,  4 },
+  {  64, 64,  32,  4 },
+  { 112, 52,  32,  4 },
+  {  32, 40,  24,  4 },
+  {  88, 28,  40,  4 },
+};
+#define N_PLATFORMS (sizeof(platforms) / sizeof(platforms[0]))
+
+static uint8_t on_platform(int16_t px, int16_t py) {
+  uint8_t i;
+  for (i = 0; i < N_PLATFORMS; i++) {
+    if (py + 6 == platforms[i].y
+        && px + 6 > platforms[i].x
+        && px     < platforms[i].x + platforms[i].w) return 1;
+  }
+  return 0;
+}
+
+void main(void) {
+  int16_t px = 80, py = 88;
+  int8_t  vy = 0;
+  uint8_t joy, prev = 0, btn, grounded;
+  uint8_t i;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+  joy_install(&lynx_stdjoy_joy);
+  sfx_init();
+
+  for (;;) {
+    tgi_clear();
+    tgi_setcolor(COLOR_GREY);
+    for (i = 0; i < N_PLATFORMS; i++) {
+      tgi_bar(platforms[i].x, platforms[i].y, platforms[i].x + platforms[i].w - 1, platforms[i].y + platforms[i].h - 1);
+    }
+    tgi_setcolor(COLOR_YELLOW);
+    tgi_bar((unsigned)px, (unsigned)py, (unsigned)(px + 6), (unsigned)(py + 6));
+    tgi_updatedisplay();
+    sfx_update();
+
+    joy = joy_read(JOY_1);
+    btn = JOY_BTN_1(joy) ? 1 : 0;
+    grounded = on_platform(px, py);
+
+    if (JOY_LEFT(joy)  && px > 0)   px--;
+    if (JOY_RIGHT(joy) && px < 154) px++;
+    if (btn && !prev && grounded) { vy = -6; sfx_tone(0, 100, 6); }
+    prev = btn;
+
+    vy++;
+    if (vy > 4) vy = 4;
+    py += vy;
+    if (py < 0)  py = 0;
+    if (py > 96) py = 96;
+    if (vy > 0 && on_platform(px, py)) { py = py & 0xFC; vy = 0; }
+  }
+}

package/examples/lynx/templates/puzzle.c

@@ -0,0 +1,142 @@
+// ── puzzle.c — Atari Lynx match-3 falling-block puzzle ──────────────
+//
+// 6×12 grid drawn with tgi_bar. 3 cell colors. 1×3 active piece,
+// rotate / soft-drop / hard-drop / horizontal-triple clear + score.
+
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include <stdint.h>
+#include "lynx_sfx.h"
+
+#define COLS 6
+#define ROWS 12
+#define CELL_PX 8
+#define GRID_X 56
+#define GRID_Y 4
+
+static uint8_t grid[ROWS][COLS];
+static uint8_t piece[3];
+static int8_t piece_x, piece_y;
+static uint8_t fall_timer;
+static uint16_t score;
+static uint32_t rng = 1;
+
+static uint8_t rng_pick(void) {
+  rng = rng * 1103515245u + 12345u;
+  return (uint8_t)(1 + (rng >> 16) % 3);
+}
+
+static void new_piece(void) {
+  piece[0] = rng_pick();
+  piece[1] = rng_pick();
+  piece[2] = rng_pick();
+  piece_x = COLS / 2 - 1;
+  piece_y = -3;
+}
+
+static uint8_t collides(int8_t x, int8_t y) {
+  uint8_t i;
+  int8_t r;
+  if (x < 0 || x >= COLS) return 1;
+  for (i = 0; i < 3; i++) {
+    r = (int8_t)(y + i);
+    if (r >= ROWS) return 1;
+    if (r >= 0 && grid[r][x] != 0) return 1;
+  }
+  return 0;
+}
+
+static void lock_piece(void) {
+  uint8_t i, c;
+  int8_t r;
+  uint8_t a, b, d;
+  for (i = 0; i < 3; i++) {
+    r = (int8_t)(piece_y + i);
+    if (r >= 0 && r < ROWS) grid[r][piece_x] = piece[i];
+  }
+  for (i = 0; i < 3; i++) {
+    r = (int8_t)(piece_y + i);
+    if (r < 0 || r >= ROWS) continue;
+    for (c = 0; c <= COLS - 3; c++) {
+      a = grid[r][c]; b = grid[r][c+1]; d = grid[r][c+2];
+      if (a != 0 && a == b && b == d) {
+        grid[r][c] = 0; grid[r][c+1] = 0; grid[r][c+2] = 0;
+        if (score < 65500) score += 30;
+        sfx_tone(0, 60, 10);
+      }
+    }
+  }
+}
+
+static uint8_t cell_color(uint8_t v) {
+  switch (v) {
+    case 1: return COLOR_RED;
+    case 2: return COLOR_GREEN;
+    case 3: return COLOR_BLUE;
+    default: return COLOR_BLACK;
+  }
+}
+
+void main(void) {
+  uint8_t joy, prev = 0, fall_rate, t;
+  uint8_t r, c, i;
+  int8_t pr;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+  joy_install(&lynx_stdjoy_joy);
+  sfx_init();
+
+  for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) grid[r][c] = 0;
+  score = 0; fall_timer = 0;
+  new_piece();
+
+  for (;;) {
+    tgi_clear();
+    /* grid */
+    for (r = 0; r < ROWS; r++) for (c = 0; c < COLS; c++) {
+      if (grid[r][c] != 0) {
+        tgi_setcolor(cell_color(grid[r][c]));
+        tgi_bar(GRID_X + c * CELL_PX, GRID_Y + r * CELL_PX,
+                GRID_X + c * CELL_PX + CELL_PX - 1, GRID_Y + r * CELL_PX + CELL_PX - 1);
+      }
+    }
+    /* piece */
+    for (i = 0; i < 3; i++) {
+      pr = (int8_t)(piece_y + i);
+      if (pr < 0 || pr >= ROWS) continue;
+      tgi_setcolor(cell_color(piece[i]));
+      tgi_bar(GRID_X + piece_x * CELL_PX, GRID_Y + pr * CELL_PX,
+              GRID_X + piece_x * CELL_PX + CELL_PX - 1, GRID_Y + pr * CELL_PX + CELL_PX - 1);
+    }
+    tgi_updatedisplay();
+    sfx_update();
+
+    joy = joy_read(JOY_1);
+    if (JOY_LEFT(joy)  && !(prev & 4) && !collides(piece_x - 1, piece_y)) piece_x--;
+    if (JOY_RIGHT(joy) && !(prev & 8) && !collides(piece_x + 1, piece_y)) piece_x++;
+    if (JOY_BTN_1(joy) && !(prev & 0x10)) {
+      t = piece[0]; piece[0] = piece[1]; piece[1] = piece[2]; piece[2] = t;
+      sfx_tone(1, 40, 2);
+    }
+    if (JOY_BTN_2(joy) && !(prev & 0x20)) {
+      while (!collides(piece_x, (int8_t)(piece_y + 1))) piece_y++;
+      lock_piece();
+      new_piece();
+    }
+    prev = (JOY_LEFT(joy) ? 4 : 0) | (JOY_RIGHT(joy) ? 8 : 0)
+         | (JOY_BTN_1(joy) ? 0x10 : 0) | (JOY_BTN_2(joy) ? 0x20 : 0);
+
+    fall_rate = JOY_DOWN(joy) ? 4 : 30;
+    if (++fall_timer >= fall_rate) {
+      fall_timer = 0;
+      if (collides(piece_x, (int8_t)(piece_y + 1))) {
+        lock_piece();
+        new_piece();
+      } else {
+        piece_y++;
+      }
+    }
+  }
+}

package/examples/lynx/templates/racing.c

@@ -0,0 +1,94 @@
+// ── racing.c — Atari Lynx 3-lane top-down racer ──────────────────────
+
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include <stdint.h>
+#include "lynx_sfx.h"
+
+#define MAX_OBS 4
+#define LANE0 32
+#define LANE1 76
+#define LANE2 120
+
+static const uint8_t lane_x[3] = { LANE0, LANE1, LANE2 };
+
+typedef struct { int16_t x, y, alive; } Car;
+
+void main(void) {
+  uint8_t player_lane = 1;
+  Car player = { LANE1, 90, 1 };
+  Car obs[MAX_OBS];
+  uint8_t spawn = 0, prev = 0;
+  uint8_t game_over = 0;
+  uint8_t joy, i;
+  uint32_t rng = 1;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+  joy_install(&lynx_stdjoy_joy);
+  sfx_init();
+  for (i = 0; i < MAX_OBS; i++) obs[i].alive = 0;
+
+  for (;;) {
+    tgi_clear();
+    /* lane lines */
+    tgi_setcolor(COLOR_DARKGREY);
+    tgi_line(28, 0, 28, 101);
+    tgi_line(72, 0, 72, 101);
+    tgi_line(116, 0, 116, 101);
+    tgi_line(160, 0, 160, 101);
+
+    tgi_setcolor(COLOR_YELLOW);
+    tgi_bar((unsigned)player.x - 4, (unsigned)player.y - 4, (unsigned)player.x + 4, (unsigned)player.y + 4);
+    tgi_setcolor(COLOR_RED);
+    for (i = 0; i < MAX_OBS; i++) {
+      if (obs[i].alive) tgi_bar((unsigned)obs[i].x - 4, (unsigned)obs[i].y - 4, (unsigned)obs[i].x + 4, (unsigned)obs[i].y + 4);
+    }
+    tgi_updatedisplay();
+    sfx_update();
+
+    if (game_over > 0) {
+      game_over--;
+      if (game_over == 0) {
+        for (i = 0; i < MAX_OBS; i++) obs[i].alive = 0;
+        player_lane = 1; player.x = LANE1;
+      }
+      continue;
+    }
+
+    joy = joy_read(JOY_1);
+    if (JOY_LEFT(joy)  && !(prev & 4) && player_lane > 0) { player_lane--; sfx_tone(1, 70, 2); }
+    if (JOY_RIGHT(joy) && !(prev & 8) && player_lane < 2) { player_lane++; sfx_tone(1, 70, 2); }
+    player.x = lane_x[player_lane];
+    prev = (JOY_LEFT(joy) ? 4 : 0) | (JOY_RIGHT(joy) ? 8 : 0);
+
+    for (i = 0; i < MAX_OBS; i++) {
+      if (!obs[i].alive) continue;
+      obs[i].y += 2;
+      if (obs[i].y >= 110) obs[i].alive = 0;
+    }
+    spawn++;
+    if (spawn >= 30) {
+      spawn = 0;
+      for (i = 0; i < MAX_OBS; i++) {
+        if (!obs[i].alive) {
+          rng = rng * 1103515245u + 12345u;
+          obs[i].x = lane_x[(rng >> 16) % 3];
+          obs[i].y = 0;
+          obs[i].alive = 1;
+          break;
+        }
+      }
+    }
+    for (i = 0; i < MAX_OBS; i++) {
+      if (obs[i].alive
+          && obs[i].x > player.x - 8 && obs[i].x < player.x + 8
+          && obs[i].y > player.y - 8 && obs[i].y < player.y + 8) {
+        game_over = 60;
+        sfx_noise(30);
+        break;
+      }
+    }
+  }
+}

package/examples/lynx/templates/shmup.c

@@ -0,0 +1,132 @@
+// ── shmup.c — Atari Lynx vertical-shooter scaffold ───────────────────
+//
+// Cross-platform shmup: player + 4 bullets + 4 enemies (pools), wave
+// spawner, AABB collisions, MIKEY sound effects. cc65's tgi handles
+// Suzy's blitter for us.
+
+#include <tgi.h>
+#include <joystick.h>
+#include <lynx.h>
+#include <stdint.h>
+#include "lynx_sfx.h"
+
+#define MAX_BULLETS 4
+#define MAX_ENEMIES 4
+
+typedef struct { uint8_t x, y, alive; } Obj;
+
+static Obj player;
+static Obj bullets[MAX_BULLETS];
+static Obj enemies[MAX_ENEMIES];
+static uint8_t spawn_timer;
+static uint8_t prev_btn;
+
+static uint8_t aabb(Obj *a, Obj *b) {
+  return a->x < b->x + 6 && a->x + 6 > b->x
+      && a->y < b->y + 6 && a->y + 6 > b->y;
+}
+
+static void fire(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_BULLETS; i++) {
+    if (!bullets[i].alive) {
+      bullets[i].x = player.x;
+      bullets[i].y = player.y - 4;
+      bullets[i].alive = 1;
+      return;
+    }
+  }
+}
+
+static void spawn(void) {
+  uint8_t i;
+  for (i = 0; i < MAX_ENEMIES; i++) {
+    if (!enemies[i].alive) {
+      enemies[i].x = (uint8_t)(8 + ((spawn_timer * 37) & 0x7F));
+      enemies[i].y = 0;
+      enemies[i].alive = 1;
+      return;
+    }
+  }
+}
+
+void main(void) {
+  uint8_t joy, fire_now, i, j;
+
+  tgi_install(&lynx_160_102_16_tgi);
+  tgi_init();
+  joy_install(&lynx_stdjoy_joy);
+  sfx_init();
+
+  player.x = 76; player.y = 90; player.alive = 1;
+  for (i = 0; i < MAX_BULLETS; i++) bullets[i].alive = 0;
+  for (i = 0; i < MAX_ENEMIES; i++) enemies[i].alive = 0;
+  spawn_timer = 0;
+  prev_btn = 0;
+
+  for (;;) {
+    /* CANONICAL LYNX GAME LOOP — full-redraw every frame. The reliable order:
+     *   1. WAIT for the Suzy blitter to finish the previous frame:
+     *        while (tgi_busy()) { }
+     *      Skipping this is the #1 "Lynx screen stays blank" trap — drawing
+     *      while the blitter is mid-flight loses the frame.
+     *   2. CLEAR with a full-screen tgi_bar in the background colour, NOT
+     *      tgi_clear() (which can leave the framebuffer stale in this
+     *      toolchain+emulator path).
+     *   3. DRAW every object.
+     *   4. tgi_updatedisplay() to push the frame. */
+    while (tgi_busy()) { }
+    tgi_setcolor(COLOR_BLACK);
+    tgi_bar(0, 0, tgi_getmaxx(), tgi_getmaxy());  /* maxx/maxy = 159/101 = full screen */
+
+    /* Render */
+    tgi_setcolor(COLOR_YELLOW);
+    tgi_bar(player.x, player.y, player.x + 6, player.y + 6);
+    tgi_setcolor(COLOR_WHITE);
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (bullets[i].alive) tgi_bar(bullets[i].x, bullets[i].y, bullets[i].x + 2, bullets[i].y + 4);
+    }
+    tgi_setcolor(COLOR_RED);
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      if (enemies[i].alive) tgi_bar(enemies[i].x, enemies[i].y, enemies[i].x + 6, enemies[i].y + 6);
+    }
+    tgi_updatedisplay();
+    sfx_update();
+
+    /* Input + state */
+    joy = joy_read(JOY_1);
+    fire_now = JOY_BTN_1(joy) ? 1 : 0;
+    if (JOY_LEFT(joy)  && player.x > 0)   player.x--;
+    if (JOY_RIGHT(joy) && player.x < 154) player.x++;
+    if (JOY_UP(joy)    && player.y > 8)   player.y--;
+    if (JOY_DOWN(joy)  && player.y < 96)  player.y++;
+    if (fire_now && !prev_btn) { fire(); sfx_tone(0, 80, 4); }
+    prev_btn = fire_now;
+
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (!bullets[i].alive) continue;
+      if (bullets[i].y < 2) { bullets[i].alive = 0; continue; }
+      bullets[i].y -= 3;
+    }
+    for (i = 0; i < MAX_ENEMIES; i++) {
+      if (!enemies[i].alive) continue;
+      enemies[i].y++;
+      if (enemies[i].y >= 102) enemies[i].alive = 0;
+    }
+    spawn_timer++;
+    if (spawn_timer >= 28) { spawn_timer = 0; spawn(); }
+
+    for (i = 0; i < MAX_BULLETS; i++) {
+      if (!bullets[i].alive) continue;
+      for (j = 0; j < MAX_ENEMIES; j++) {
+        if (!enemies[j].alive) continue;
+        if (aabb(&bullets[i], &enemies[j])) {
+          bullets[i].alive = 0;
+          enemies[j].alive = 0;
+          sfx_noise(8);
+          break;
+        }
+      }
+    }
+  }
+}