matcha

matcha

A Game Boy and Game Boy Color emulator you can see inside — and that Claude can play.

One portable Rust core (no_std, zero dependencies, no unsafe) with three hosts:

• Web player — a single offline HTML file: sound, keyboard/touch/gamepad, battery saves, save states, 20 seconds of rewind, and a live debugger (CPU, disassembly, per-line PPU timing, VRAM, audio channels, RAM search). Four open-source homebrew games are on the shelf.
• Claude plugin — an MCP server with 17 tools (load_rom, press, screenshot, breakpoint, find_value, …) and three skills, so Claude can play, test and debug Game Boy software. Node only; no npm packages.
• matcha CLI — headless runs and screenshots, the conformance scoreboard, a profiler, an instruction tracer and a disassembler.

And a study: every Homebrew Hub cartridge an original Game Boy can run — 868 of them — played for a minute by matcha and by SameBoy side by side (docs/analysis.md). The comparison found three matcha bugs, since fixed. The new automatic DMG/CGB study revalidates all 1,235 supported-mapper cartridges from the same pinned corpus.

Accuracy

Generated by matcha test — full list in docs/CONFORMANCE.md.

Suite	Passed
SingleStepTests SM83 (every opcode, every bus cycle)	498,000 / 498,000
Mooneye (DMG-applicable acceptance + emulator-only)	94 / 94
dmg-acid2	1 / 1
Blargg (cpu, timing, sound, OAM bug)	43 / 43
Gambatte (DMG hex-result and screenshot tests)	1,642 / 1,783
Mealybug Tearoom (mid-scanline effects)	9 / 24

The pixel FIFO now applies palette, scroll and window changes during a scanline. Native Game Boy Color adds banked memory, RGB palettes, double-speed CPU operation and VRAM DMA. Both cgb-acid2 and cgb-acid-hell match their reference images exactly. The separate CGB scoreboard records the remaining timing failures and excluded compatibility-mode tests. DMG-on-CGB colourization and precise hardware quirks remain; see ROADMAP.md.

Reproduce a homebrew debugging session

With Node 18 or newer, run node mcp/debug-homebrew.mjs. No package install, ROM download or credentials are needed. The script creates a small original program, identifies the instruction writing $42 to $C000, steps to the next write, and proves that save/restore replays it exactly. It also verifies rejected requests preserve the machine, save slots, breakpoints, search and palette. See the manual MCP walkthrough for the tool calls and known limits. This is debugger workflow evidence, not a hardware accuracy score.

Download 0.1.1

Get matcha.plugin, matcha.html and SHA256SUMS from the 0.1.1 release. The plugin is a ZIP archive containing the standalone MCP server; the HTML is an offline web player. Neither needs a Rust build. Node 18+ is required for MCP. The Rust CLI remains a source build.

For a generic MCP client, extract matcha.plugin into a new directory and add this stdio server, replacing the path with its actual absolute location:

{"mcpServers":{"matcha":{"command":"node","args":["/absolute/path/matcha-plugin/server/server.mjs"]}}}

Run shasum -a 256 -c SHA256SUMS after downloading all listed assets (or use a SHA-256 checker for the individual asset you downloaded). The release manifest records the source commit and WASM hash; checksums identify files but do not establish trust in their publisher. Bundled homebrew notices are retained in the plugin and HOMEBREW-LICENSES.md. Only use ROMs you are allowed to run.

Follow the homebrew debugger exercise using the source archive from the same tag; its fixture generator and tests are plain Node files. Save slots live in the MCP process and are lost when it exits.

Quick start

# Play: open the bundled page (after building it once, see below)
open dist/matcha.html

# Claude plugin: install dist/matcha.plugin in the Claude desktop app

# CLI
cargo build --release
target/release/matcha run game.gb --seconds 10 --screenshot shot.png
target/release/matcha run color.gbc --model auto --screenshot color.png
target/release/matcha trace game.gb --input monkey --last 50
target/release/matcha run game.gb --ram noise   # power on with junk in RAM, as hardware does
target/release/matcha disasm game.gb --addr 0150

# Tests
scripts/fetch-testdata.sh                 # test ROMs + SingleStepTests (not committed)
cargo test --workspace                    # unit tests + 498k CPU cases
target/release/matcha test testdata/roms --baseline docs/conformance.json
target/release/matcha test testdata/roms --model cgb --baseline docs/conformance-cgb.json

# Builds
scripts/build-wasm.sh                     # core -> web/matcha.wasm
node scripts/build-web.mjs                # dist/matcha.html
scripts/build-plugin.sh                   # dist/matcha.plugin

The web player, JavaScript wrapper, CLI and MCP choose CGB for colour-capable cartridges by default; --model dmg / --model cgb or the corresponding model option overrides this. The Rust GameBoy::new API remains DMG; use GameBoy::new_with_model for explicit native CGB.

Keys in the web player: arrows, X = A, Z = B, Enter = Start, Backspace = Select; Space pause, R rewind (hold), F fast-forward, N next frame, I step, S/L save/load state, M sound.

Save-state format is now version 4. Older quick-save snapshots cannot be loaded; cartridge battery saves keep their existing format.

How it's built

docs/ARCHITECTURE.md	System design: timing model, components, data flow, interfaces, performance
docs/adr/	Ten decision records (timing, PPU, portability, WASM ABI, audio, save states, MCP, verification, pixel FIFO, native CGB)
docs/analysis.md	The homebrew corpus study and the SameBoy comparison
AGENTS.md	Rules and commands for anyone changing the code
CONTINUE.md	Current state and how to pick the work up

crates/matcha-core   the emulator (CPU, PPU, APU, timer, cartridges, save states, debugger, profiler)
crates/matcha-cli    matcha: run, test, profile, trace, disasm, info
crates/matcha-wasm   C-ABI WebAssembly exports
web/                 JS wrapper, player source, bundled homebrew
mcp/                 MCP server + end-to-end test
plugin/              Claude plugin (skills, manifest)
analysis/            corpus study pipeline (manifest, profiling, SameBoy reference, report)

License

MIT or Apache-2.0, at your option. The bundled homebrew ROMs keep their own licences (web/roms/LICENSES.md).