romdev-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,45 @@
+MIT License
+
+Copyright (c) 2026 Luis Montes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The MIT license above applies to the ORIGINAL romdev code authored in this
+repository — the MCP server, tools, scaffolds, build glue, JavaScript host,
+and documentation.
+
+romdev bundles and redistributes third-party emulator cores, compiler
+toolchains, and game runtime libraries, each under its OWN license. The MIT
+grant above does NOT relicense those components; see NOTICE for the full
+inventory and the license that governs each.
+
+GAMES YOU BUILD WITH ROMDEV ARE YOURS — including to sell commercially. A ROM
+romdev produces contains only your own code plus permissive runtime libraries
+(SGDK, PVSnesLib, libtonc/libgba, hUGEDriver, FamiTone, maxmod —
+MIT/ISC/zlib/public-domain), compiled by toolchains that carry runtime
+exceptions. Nothing romdev places in your ROM restricts using or selling it.
+
+The only license caveat concerns redistributing the romdev TOOL BUNDLE itself:
+two bundled emulator cores (snes9x, genesis_plus_gx) are under non-commercial
+licenses, so the bundle as a whole is distributed as source-available and free
+for non-commercial use (and isn't labeled OSI "open source"), even though this
+repository's own code is MIT. Those cores are a dev instrument that never ships
+inside a built game. Read NOTICE before redistributing the tool bundle.

package/NOTICE

@@ -0,0 +1,86 @@
+romdev — third-party component inventory
+========================================
+
+TL;DR — Games you build with romdev are YOURS, including to sell commercially.
+A built ROM contains only your code + permissive runtime libraries, compiled by
+toolchains with runtime exceptions. The non-commercial caveat below applies ONLY
+to redistributing the romdev tool bundle (which contains two non-commercial
+emulator cores) — never to the games you make with it.
+
+romdev's own code is MIT (see LICENSE). It bundles and redistributes
+third-party emulator cores, compiler toolchains, and game runtime libraries,
+each under its own license. This file inventories them.
+
+Two kinds of bundled component, governed differently:
+
+  • COMPILERS / TOOLCHAINS produce the user's ROM. Several are GPL/LGPL, but
+    compilers carry a RUNTIME EXCEPTION: the license of the compiler does NOT
+    extend to its output. A game compiled with GPL gcc/cc65/sdcc is the
+    author's own work, freely licensable. The GPL obligation falls on US (we
+    redistribute the compiler binary) — satisfied by shipping the build recipe
+    + pinned upstream source so anyone can reproduce the binary (see
+    packages/romdev/scripts/ and BUILDING.md).
+
+  • EMULATOR CORES never touch the user's ROM — they are a dev instrument
+    (run + observe). Their license governs only OUR redistribution of the core
+    binary. Most are GPL (OSI open source, source available upstream). Two are
+    NON-COMMERCIAL (see below), which is why romdev as a whole is distributed
+    as SOURCE-AVAILABLE / FREE FOR NON-COMMERCIAL USE rather than OSI open
+    source. romdev's own code is MIT and the game runtime libraries are
+    permissive, so games you BUILD with romdev are unencumbered (see below);
+    the non-commercial terms apply only to redistributing the bundled core
+    binaries themselves.
+
+
+NON-COMMERCIAL COMPONENTS (why romdev is "free for non-commercial use")
+-----------------------------------------------------------------------
+These two cores are under custom NON-COMMERCIAL licenses. They forbid
+commercial redistribution of the core, so a distribution of romdev that
+bundles them is free for non-commercial use and is not labeled OSI open
+source. (Your code is MIT; your built games are unencumbered — this affects
+only redistribution of these emulator binaries.)
+
+  snes9x            SNES core           non-commercial (snes9x license)
+  genesis_plus_gx   Genesis/SMS/GG core non-commercial (Genesis Plus GX license)
+
+
+Emulator cores
+--------------
+  fceumm            NES                 GPL-2.0
+  gambatte          GB / GBC            GPL-2.0
+  genesis_plus_gx   Genesis / SMS / GG  non-commercial  ⚠ (see above)
+  snes9x            SNES                non-commercial  ⚠ (see above)
+  mgba              GBA                 MPL-2.0
+  vice (x64)        C64                 GPL-2.0
+  stella2014        Atari 2600          GPL-2.0
+  prosystem         Atari 7800          GPL-2.0
+  handy             Atari Lynx          zlib
+
+Compiler toolchains  (runtime exception — does not encumber compiled ROMs)
+--------------------------------------------------------------------------
+  cc65              NES/C64/2600/7800/Lynx   zlib
+  sdcc              GB/GBC/SMS/GG            GPL-2.0 (runtime libs: GPL + linking exception)
+  arm-none-eabi-gcc GBA                     GPL-3.0 (GCC Runtime Library Exception)
+  m68k-elf-gcc      Genesis (C)             GPL-3.0 (GCC Runtime Library Exception)
+  binutils          (gcc toolchains)        GPL-3.0
+  newlib            (gcc toolchains)        BSD-style (mixed permissive)
+  asar              SNES (asm)              LGPL-3.0
+  dasm              Atari 2600 (asm)        GPL-2.0
+  vasm (m68k)       Genesis (asm)           free for any use (vasm license)
+  rgbds             GB/GBC (asm)            MIT
+  tcc816            SNES (C)                LGPL-2.1
+  wla-dx            SNES (asm)              GPL-2.0
+
+Game runtime / SDK libraries  (linked into the user's game; shipped as source)
+------------------------------------------------------------------------------
+  SGDK              Genesis C engine        MIT
+  PVSnesLib         SNES C library          MIT
+  libtonc / libgba  GBA C libraries         public domain / zlib-style
+  maxmod / mmutil   GBA music               ISC
+  hUGEDriver        GB/GBC music            MIT-style (see LICENSE-HUGEDRIVER)
+  FamiTone2         NES music               permissive (see LICENSE-FAMITONE)
+
+Full license texts for the bundled SDK libraries live alongside their source
+under packages/romdev/src/platforms/*/lib/. Emulator-core and compiler license
+texts travel with their upstream source, which is fetched at build time from
+the pinned commits recorded in packages/romdev/scripts/versions.json.

package/README.md

@@ -0,0 +1,46 @@
+# romdev
+
+The entry point for **romdev** — vibe-code real retro games. Lets a coding agent build, run, and inspect actual homebrew ROMs (NES, SNES, Game Boy, Genesis, Atari, C64, GBA, and more) with one command.
+
+```bash
+npx romdev-mcp
+```
+
+This package is the [Model Context Protocol](https://modelcontextprotocol.io/) server and CLI. It contains all the JavaScript — the MCP tool surface, the WASM libretro host, the per-platform scaffolds, runtime/library source, and debug helpers — but **no emulator or compiler WASM itself.** Those ship in the `romdev-*` binary packages this package depends on, and are loaded on demand the first time you build or run a given platform.
+
+> For the full project — what romdev is, the supported-platform matrix, how the pieces fit together, and how to develop on it — see the [repository README](https://github.com/monteslu/romdev#readme).
+
+## What's in this package
+
+- **`bin`**
+  - `romdev-mcp` → the MCP server (`src/mcp/server.js`). Streamable-HTTP transport on `http://127.0.0.1:7331/mcp` by default (`PORT` / `HOST` to override).
+  - `romdev-mcp-cli` → a smoke/utility CLI, incl. `romdev-mcp-cli play <rom>` (SDL window, hot-plug controllers).
+- **`src/`** — the server, MCP tools, WASM host, core/toolchain resolvers, per-platform memory interpretation, and bundled library/runtime source (cc65 libs, PVSnesLib, SGDK, libtonc/libgba, hUGEDriver, …) that scaffolded projects link against.
+- **`examples/`** — per-platform starter projects and genre scaffolds.
+
+## Dependencies
+
+`romdev-mcp` hard-depends (exact-pinned) on the binary packages that carry the WebAssembly, so a single install gets a matched, tested set:
+
+- Cores: `romdev-core-{fceumm,gambatte,gpgx,vice,handy,prosystem}`
+- Platforms: `romdev-platform-{snes,gba,atari2600}`
+- Toolchains: `romdev-toolchain-{cc65,sdcc,m68k-gcc,vasm,rgbds}`
+
+`@kmamal/sdl` is an optional dependency used only by `playtest()` / `romdev-mcp-cli play`. If it fails to install, the headless server still runs — only the live-window features degrade.
+
+## Connect
+
+```bash
+npx romdev-mcp
+# then, e.g. for Claude Code:
+claude mcp add --transport http romdev http://127.0.0.1:7331/mcp
+```
+
+Agents: the server delivers [`AGENTS.md`](./AGENTS.md) as connection-time instructions — the workflow guide for the full tool surface. Or just connect your agent and call `listCategories` / `describeTool` to explore the tools live.
+
+## License
+
+romdev's code is **MIT**, and **the games you build are yours — including to
+sell.** Full details + third-party component inventory:
+[LICENSE](https://github.com/monteslu/romdev/blob/main/LICENSE) and
+[NOTICE](https://github.com/monteslu/romdev/blob/main/NOTICE).

package/examples/README.md

@@ -0,0 +1,36 @@
+# Examples
+
+Minimal "hello" projects for every platform romdev's bundled toolchains can build. Each one is the simplest thing that's still a real ROM — an agent forks from these instead of starting from a blank file.
+
+Each example fits the convention:
+- A `main.c` or `main.asm`/`main.s` as the entry point.
+- Builds with `buildSource({ platform, source })` (most platforms) or with
+  the per-platform extra below.
+- Produces a runnable ROM for the matching emulator core.
+
+| Platform     | Source               | Toolchain | Extra build args                     |
+| ------------ | -------------------- | --------- | ------------------------------------ |
+| nes          | `nes/main.c`         | cc65      | `linkerConfig: "chr-ram"` (writes tiles at runtime via PPUADDR/PPUDATA; preset defines OAM segment + drops CHR-ROM region) |
+| nes (full game) | `nes/space-shooter/` | cc65   | Canonical complete-game reference — a generic fixed-shooter showing "NES-shaped C": bit-packed alien state, 5-col formation for the 8-sprite/scanline limit, correct OAM-staging order, shields/HUD as BG tiles, CHR-RAM upload, APU SFX. Build with `linkerConfig: "chr-ram-runtime"` + `nes_runtime.c`. See its README. |
+| c64          | `c64/main.c`         | cc65      | Direct VIC-II + screen-RAM demo: paints background, writes screen codes for "HELLO ROM-DEV-MCP" into screen RAM with white-on-blue color, cycles the border color. C89 (cc65) — no mixed decl/code. |
+| atari2600    | `atari2600/main.asm` | dasm      | Standard NTSC kernel (3 vsync + 37 vblank + 192 visible + 30 overscan) with a single GRP0 sprite, joystick-driven movement, and the vector table at $FFFA. |
+| atari2600 (gallery shooter) | `atari2600/templates/mini_invaders.asm` | dasm | Fixed-shooter 2600 game using the RIGHT TIA objects (not playfield "barcode" bars): P0 double-width cannon, P1 + NUSIZ1=%011 = a row of 3 hardware-replicated invaders, M0 = shot. Aliens march + drop at edges; button fires. The honest 2600-idiomatic genre layout. `createProject({platform:"atari2600", template:"mini_invaders"})`. |
+| atari7800    | `atari7800/main.c`   | cc65      | Minimal MARIA bring-up: DLL pointing at a single-zone DL, palette load, CHARBASE = 0. cc65 can't constant-fold pointer→int for static initializers, so the DL/DLL addresses are patched in at runtime in `main()`. |
+| lynx         | `lynx/main.c`        | cc65      |                                      |
+| snes         | `snes/main.asm`      | asar      |                                      |
+| genesis      | `genesis/main.s`     | vasm68k   |                                      |
+| gb           | `gb/main.c` (default) or `gb/main.asm` (`language:"asm"`) | sdcc sm83 port (C, default) / rgbds (asm) | C example cycles the BG palette every 32 frames. Asm example shows yellow 'H' on light BG, scrollable with A. SDCC GB hardware-register headers under `src/platforms/gb/lib/c/gb_hardware.h`. |
+| gbc          | `gbc/main.asm`       | rgbds (asm) / sdcc sm83 (C) | The bundled example is an asm CGB-color demo (yellow 'H' on a true-blue BG, only possible on GBC). C is also supported via SDCC sm83 — same as GB. |
+| sms          | `sms/main.c` (or `sms/templates/*.c`) | sdcc | Pair with `src/platforms/sms/lib/c/sms_crt0.s` (passed via `crt0` arg) — boots into a real cartridge with vector table + SP=$DFF0 + IM 1. Yellow 'H' on blue, scrollable with P1-B1. The 9 templates under `sms/templates/` (default, hello_sprite, tile_engine, shmup, shmup_2p, platformer, puzzle, sports, racing, music_demo) all use this crt0 — `createProject` copies it in automatically. |
+| gg           | `gg/templates/default.c` (or any other template) | sdcc | R53: GG now ships `src/platforms/gg/lib/c/gg_crt0.s` (byte-identical to SMS's). Real visible-and-runnable default: VDP Mode 4 init + palette + yellow 'H' centered in the 160×144 visible viewport + B1 scroll loop. The 9 templates (default, hello_sprite, tile_engine, shmup, platformer, puzzle, sports, racing, music_demo) all link the GG runtime + crt0 via `createProject({platform:"gg"})`. |
+| gba          | `gba/templates/*.c`  | arm-none-eabi-gcc | Default runtime = **libtonc** (`#include <tonc.h>`). 9 scaffolds incl. `tonc_hello`, `tonc_hello_sprite`, the 5 genre scaffolds, and `maxmod_demo` (music). Pass `runtime:"libgba"` for the devkitPro API, `runtime:"none"` for bare newlib. **Always call `irq_init(NULL); irq_add(II_VBLANK, NULL);` before `VBlankIntrWait()`** — otherwise the BIOS halts forever. |
+
+## Guides
+
+- **[porting-across-platforms/](porting-across-platforms/README.md)** — building
+  the *same* arcade game on many systems? Read this first. A per-platform matrix
+  of the right rendering primitive (OAM sprites vs. VIC chars vs. Lynx blitter
+  vs. 7800 display-lists vs. 2600 beam-raced TIA) so you don't get "correct but
+  ugly" output. Prototype on GBA/Genesis, then port the render layer downward.
+- **[art-first-workflow/](art-first-workflow/README.md)** — converting pixel-art
+  editor output (Aseprite/Tiled/GIF/TexturePacker) into platform-native tiles.

package/examples/art-first-workflow/README.md

@@ -0,0 +1,205 @@
+# Art-first workflow — FOSS tools → ROM
+
+The goal: a non-coder using only open-source tools (LibreSprite, Tiled,
+Pixelorama, GIMP) can author a retro game and get a working ROM
+without ever editing C/asm. Zero installs beyond the editors. Zero
+shelling out from the agent.
+
+## The toolchain
+
+| Step | Tool | License | Format |
+|---|---|---|---|
+| Pick a palette | [Lospec](https://lospec.com) → save `.hex` | CC0 palettes | hex/JSON |
+| Draw sprites | [LibreSprite](https://libresprite.github.io/) | GPLv2 (Aseprite fork) | `.ase` |
+| Design levels | [Tiled](https://www.mapeditor.org/) | BSD-2 | `.tmj` (JSON) |
+| Animate | LibreSprite (export GIF) or any GIF editor | various | `.gif` |
+| Build ROM | romdev `loadAsepriteSheet` / `loadTilemap` / `loadGifAnimation` | MIT | platform tiles |
+
+Every tool runs on Linux/Mac/Windows. No native dependencies, no
+build steps, no agent shell scripts.
+
+## Step-by-step
+
+### 1. Pick a palette
+
+Get a CC0 palette from [lospec.com/palettes](https://lospec.com/palettes)
+or generate one matching your target platform:
+
+```js
+// MCP call
+getPlatformPalettePng({ platform: "nes", format: "hex", outputPath: "palette.hex" })
+// → palette.hex (one #RRGGBB per line)
+
+// Or for direct import into LibreSprite:
+getPlatformPalettePng({ platform: "nes", format: "lospec", outputPath: "palette.json" })
+// → palette.json with {name, author, colors:[hex_no_hash]}
+```
+
+### 2. Draw sprites in LibreSprite
+
+1. Open LibreSprite → **File → New** → set the size to your sprite
+   sheet (e.g. 64×64 for a 4×4 tile grid).
+2. **Palette → Open Palette** → pick `palette.hex` (or `.json` for the
+   lospec version). LibreSprite restricts you to those colors.
+3. Draw your sprites. Use **Slice tool** to name regions:
+   `player_idle`, `chalice`, `dragon_yorgle`, etc. Each named slice
+   becomes a separately addressable tile group in your game code.
+4. Use **Tags** to group frames into animations: select frames 0–3,
+   name the tag `walk_down`. Same for `walk_left`, `attack`, etc.
+5. **File → Save** as `sprites.ase`.
+
+### 3. Load sprites into your game
+
+```js
+// MCP call — returns tile bytes + named groups + tags
+loadAsepriteSheet({
+  path: "sprites.ase",
+  platform: "nes",
+  outputDir: "build",
+})
+// → {
+//     tiles: {
+//       player_idle: { tile_indices: [0, 1, 2, 3], width_tiles: 2, height_tiles: 2 },
+//       chalice:     { tile_indices: [4],         width_tiles: 1, height_tiles: 1 },
+//       ...
+//     },
+//     tile_bytes_path: "build/tiles.bin",  // upload this to CHR-RAM
+//     tile_count: 47,
+//     tags: {
+//       walk_down: { from: 0, to: 3, direction: "forward", delays_ms: [100,100,100,100] },
+//       attack:    { from: 4, to: 7, direction: "forward", delays_ms: [50,50,50,200] },
+//     },
+//     palette: [{r,g,b,a}, ...],
+//     warnings: [],
+//   }
+```
+
+Your C code references `tile_indices[0]` for "the first tile of
+player_idle" — no magic numbers. Animation timing comes from the
+artist's frame durations in LibreSprite, not hardcoded in code.
+
+### 4. Design a level in Tiled
+
+1. Open Tiled → **File → New Map** → set tile size = 8×8, map size in
+   tiles (e.g. 32×30 for a full NES screen).
+2. **New Tileset** → image-based → point at the tileset PNG you
+   exported from LibreSprite (you can also use the rendered tiles from
+   `loadAsepriteSheet` after writing to disk).
+3. Paint tiles on the **bg** layer.
+4. Add an **Object Layer** named e.g. `spawns`. Drop named point
+   objects: `player_start`, `door_north`, `chest`. Each can carry
+   key/value custom properties (e.g. `loot=potion`).
+5. **File → Export As** → "Tiled map files (.tmj)". (NOT `.tmx` — the
+   XML variant. `.tmj` is JSON and works directly.)
+
+### 5. Load the level into your game
+
+```js
+loadTilemap({
+  path: "level1.tmj",
+  platform: "nes",
+  outputDir: "build",
+})
+// → {
+//     width: 32, height: 30, tile_size: 8,
+//     layers: {
+//       bg: {
+//         width: 32, height: 30,
+//         bytes_per_cell: 1,
+//         data_path: "build/bg.data.bin",   // upload to nametable
+//         empty_path: "build/bg.empty.bin", // bitmask of "no tile here"
+//       },
+//     },
+//     object_layers: {
+//       spawns: [
+//         { id: 1, name: "player_start", type: "spawn",
+//           x: 128, y: 96, point: true,
+//           properties: { facing: "south" } },
+//         { id: 2, name: "door_north", type: "door",
+//           x: 120, y: 0, width: 16, height: 8,
+//           properties: { goes_to: "level2" } },
+//       ],
+//     },
+//     tilesets: [{ firstgid: 1, name: "world", tilewidth: 8, ... }],
+//     warnings: [],
+//   }
+```
+
+### 6. Animations from any source
+
+Got an animated GIF from anywhere (LibreSprite, GIMP, Pixelorama,
+ScreenToGif)? Parse it the same way:
+
+```js
+loadGifAnimation({
+  path: "explosion.gif",
+  platform: "nes",
+  outputDir: "build",
+})
+// → { frames: 8,
+//     tile_bytes_path: "build/tiles.bin",
+//     frame_tile_indices: [[0,1,2,3], [4,5,6,7], ...],
+//     delays_ms: [50, 50, 50, 100, ...] }
+```
+
+Or a TexturePacker-style PNG+JSON sheet (what LibreSprite's
+"Export Sprite Sheet" makes):
+
+```js
+loadSpriteSheet({
+  pngPath: "sheet.png",
+  manifestPath: "sheet.json",
+  platform: "nes",
+})
+```
+
+### 7. Wire it into your game
+
+The runtime helpers (`nes_runtime.h`, `gb_runtime.h`) already know how
+to upload tile data to CHR-RAM, write to nametable, configure OAM,
+etc. From your `main.c`:
+
+```c
+#include "nes_runtime.h"
+
+/* These would normally be `extern` and the bytes get `#include`d via
+ * `.incbin` in a separate .s file. Shown inline here for clarity. */
+extern const uint8_t tile_data[];          // from build/tiles.bin
+extern const uint8_t nametable_data[];     // from build/bg.data.bin
+
+#define PLAYER_IDLE  0
+#define CHALICE      4
+
+void main(void) {
+    ppu_off();
+    chr_ram_upload(0x0000, tile_data, /* tile_count * 16 */ );
+    palette_load(palette);
+    /* upload nametable_data straight to $2000 — vram_unsafe_set 960× */
+    oam_clear();
+    oam_spr(player_x, player_y, PLAYER_IDLE, 0);
+    ppu_on_all();
+    for (;;) {
+        ppu_wait_nmi();
+        /* update game state, walk frame index through `walk_down` tag */
+    }
+}
+```
+
+That's it. **The artist's names are the variable names.** The
+animation timing is the artist's choice. The level layout is in
+Tiled's GUI. No hand-converting PNGs, no manual tile lists, no
+ImageMagick installs.
+
+## Gotchas (see the loader docs for details)
+
+- **Tiled compression**: if Tiled's "Tile Layer Format" is set to
+  "zstd-compressed Base64", re-export with zlib/gzip/uncompressed —
+  zstd isn't supported.
+- **`.ase` tilemap-mode cels** (Aseprite 1.3+): convert to regular
+  layers first (`Layer → Convert → To Layer`).
+- **GIF disposal**: omggif (our parser) doesn't apply disposal. Export
+  GIFs with `Disposal: Replace` for full-frame sprite animations.
+- **Indexed PNG colors must match the platform palette** (±8/channel
+  tolerance). If `convertImageToTiles` warns about colors outside the
+  palette, the editor exported them slightly drifted by sRGB gamma —
+  re-export, or re-pick the palette with `getPlatformPalettePng`.

package/examples/atari2600/main.asm

@@ -0,0 +1,143 @@
+; ── Hello, Atari 2600 ──────────────────────────────────────────────
+; A complete 4 KB cart: blue background, single player sprite at center,
+; standard NTSC frame timing (3 vsync + 37 vblank + 192 visible + 30
+; overscan). Read joystick to move the sprite.
+;
+; Build: buildSource({ platform: "atari2600", source: <this file> })
+
+  processor 6502
+  org $F000
+
+; ── TIA register equates ───────────────────────────────────────────
+VSYNC    = $00
+VBLANK   = $01
+WSYNC    = $02
+COLUP0   = $06
+COLUBK   = $09
+PF1      = $0E
+RESP0    = $10
+GRP0     = $1B
+HMOVE    = $2A
+HMP0     = $20
+SWCHA    = $280
+INPT4    = $3C
+
+; ── Zero-page state ────────────────────────────────────────────────
+P_X      = $80      ; player X (column 0-159)
+P_Y      = $81      ; player top scanline (0-191)
+FRAME    = $82      ; frame counter
+
+START:
+  SEI
+  CLD
+  LDX #$FF
+  TXS
+  LDA #0
+.clr:
+  STA $00,X
+  DEX
+  BNE .clr
+
+  LDA #80
+  STA P_X
+  LDA #90
+  STA P_Y
+  LDA #$80       ; blue background
+  STA COLUBK
+  LDA #$0F       ; white player
+  STA COLUP0
+
+MAIN:
+  INC FRAME
+
+  ; ── VSYNC (3 lines) ────────────────────────────────────────────
+  LDA #2
+  STA VSYNC
+  STA WSYNC
+  STA WSYNC
+  STA WSYNC
+  LDA #0
+  STA VSYNC
+
+  ; ── VBLANK (37 lines) — game logic here ───────────────────────
+  LDA #2
+  STA VBLANK
+  LDX #37
+.vb:
+  STA WSYNC
+  DEX
+  BNE .vb
+
+  ; Read joystick and adjust P_X / P_Y (every 4th frame to throttle).
+  LDA FRAME
+  AND #$03
+  BNE .skip_move
+  LDA SWCHA
+  ASL              ; right
+  BCS .nr
+  INC P_X
+.nr:
+  ASL              ; left
+  BCS .nl
+  DEC P_X
+.nl:
+  ASL              ; down
+  BCS .nd
+  INC P_Y
+.nd:
+  ASL              ; up
+  BCS .nu
+  DEC P_Y
+.nu:
+.skip_move:
+
+  LDA #0
+  STA VBLANK
+
+  ; ── Visible (192 lines) ─────────────────────────────────────────
+  LDX #192
+.draw:
+  STA WSYNC
+  TXA
+  SEC
+  SBC P_Y
+  CMP #8
+  BCS .blank
+  TAY
+  LDA SPRITE,Y
+  STA GRP0
+  JMP .next
+.blank:
+  LDA #0
+  STA GRP0
+.next:
+  DEX
+  BNE .draw
+
+  ; ── Overscan (30 lines) ─────────────────────────────────────────
+  LDA #2
+  STA VBLANK
+  LDX #30
+.os:
+  STA WSYNC
+  DEX
+  BNE .os
+
+  JMP MAIN
+
+  ; ── Sprite shape (8 rows × 1 byte each) ─────────────────────────
+SPRITE:
+  .byte %00111100
+  .byte %01111110
+  .byte %11011011
+  .byte %11111111
+  .byte %11111111
+  .byte %11011011
+  .byte %01100110
+  .byte %01000010
+
+  ; ── Vector table ────────────────────────────────────────────────
+  org $FFFA
+  .word START
+  .word START
+  .word START