Coffee GB

A highly compatible Game Boy and Game Boy Color emulator for the desktop.

Coffee GB emulates the original Game Boy (GB/DMG) and Game Boy Color (GBC/CGB).
It is built for high compatibility across the historic game library, unusual
cartridges and accessories, and modern homebrew, demos, and diagnostic ROMs.
The reusable emulation core is written in Java; the desktop application and its
orchestration layer use Kotlin and Java.

Download and play

Coffee GB is distributed as a single executable JAR. It requires a desktop
Java 16 or newer runtime; Java 21 LTS
is recommended and is the version used by CI and release builds.

1. Download the JAR from the latest Coffee GB release.
2. Open it through your desktop's Java launcher, or start it from a terminal:

   java -jar coffee-gb-VERSION.jar

1. Choose File > Load ROM, or pass a ROM on the command line:

   java -jar coffee-gb-VERSION.jar path/to/game.gb

ROMs are not included. Coffee GB accepts .gb, .gbc, and .rom files, as
well as ZIP and 7z archives containing a ROM. On macOS, game-controller support
also requires SDL2 (brew install sdl2); keyboard input works without it.

For netplay, one player chooses Link > Start server and the other chooses
Link > Connect to server.

The next-generation pairing and consent design is frozen as protocol v9. An opt-in developer
foundation now validates CGB9 framing and HELLO capabilities. Its Part-1 API strictly parses
one-use invitations and authenticates a reserved guest slot. Its explicit Part-2 API exchanges
caller-prepared, bounded MANIFEST metadata. An additional explicit Part-3 plan enables two-sided,
item-scoped consent and one bounded ROM or battery transaction per approved proposal, then stops at
an immutable pre-START boundary. Content providers are opened only after both exact approvals;
verified receivers deliver only complete detached candidates. Callers without these opt-ins retain
their earlier boundary. Own-ROM exact match remains the default and performs no transfer.
An additional #349 developer plan enables direct StateFile-v2 checkpoints, atomic frame-safe
restore, START/READY, and bounded ACTIVE input/reset/stop. It remains opt-in and is not wired to the
default UI. Explicit v9 callers may enable bounded PING/rollback metrics and an EDT-safe sanitized
diagnostics panel. A separate trusted-LAN discovery service is off by default and advertises only
an untrusted numeric endpoint/public session ID while a listener has an open slot; confirmation
and the existing one-use authenticated invitation are still mandatory. It provides no automatic
connection, tokenless flow, matchmaking, NAT traversal, or encryption. Current user netplay
remains v8. V9 deliberately
does not interoperate or
downgrade to v8. Its TCP transport is plaintext—not confidential or secure against an on-path
attacker. See
the v9 privacy/troubleshooting guide and the
normative v9 contract. The implemented foundation boundary is
documented in netplay-v9-foundation.md.

Mobile Adapter GB support is likewise specification-only. The clean-room design treats it as a
bounded serial peripheral, never a rollback link mode, and neither connects to historical Nintendo
services nor bundles service data. See the Mobile Adapter contract.

Hardware profiles and command-line selection

Each emulation session resolves one immutable hardware profile before construction. The permanent
profile IDs are dmg, cgb, cgb0, sgb, sgb2, and mgb. Automatic selection preserves the desktop defaults;
an exact profile can be selected with:

java -jar coffee-gb-VERSION.jar --profile=cgb0 path/to/game.gbc
java -jar coffee-gb-VERSION.jar --profile=sgb2 path/to/sgb-game.gb
java -jar coffee-gb-VERSION.jar --profile=mgb path/to/game.gb

The legacy --force-dmg/-d and --force-cgb/-c flags remain available and map to dmg and
cgb. --profile cannot be combined with either force flag, and the two force flags cannot be
combined with each other. Unknown or malformed profile IDs fail before a core session is created
and report all supported IDs. Persisted uppercase DMG, CGB, CGB0, and SGB values are migrated
as finite compatibility aliases; new settings use canonical lowercase IDs. See
<code class="ra0-md-code">docs/hardware-profiles.md</code> for clocks, boot policy, state identity,
and extension rules.

The registry-generated System menu exposes Auto (default) plus every profile, including distinct
SGB, SGB2, and MGB choices. SGB2 and MGB require skip-bootstrap mode because Coffee GB does not
bundle their Nintendo boot ROMs. New SGB/SGB2/MGB local snapshots use StateFile v2 so exact model
identity and RTC phase meaning are unambiguous; old v1 snapshots remain importable. Protocol v8 is
frozen to StateFile v1, so SGB, SGB2, and MGB are rejected for netplay rather than transmitting an
ambiguous or aliased identity.

Default controls

| Action | Key |
| --- | --- |
| D-pad | Arrow keys |
| A / B | Z / X |
| Start / Select | Enter / Shift |
| Pause | Space |
| Save / load state | F5 / F7 |
| Rewind | Hold Backspace |

In single-player mode, there are ten save-state slots. Battery saves (.sav)
and save states (.sn0–.sn9) are stored next to the ROM. Pause, save
states, and rewind are disabled during netplay.

btn_up=VK_UP
btn_down=VK_DOWN
btn_left=VK_LEFT
btn_right=VK_RIGHT
btn_a=VK_Z
btn_b=VK_X
btn_start=VK_ENTER
btn_select=VK_SHIFT

input.p2.btn_up=VK_W
input.p2.btn_down=VK_S
input.p2.btn_left=VK_A
input.p2.btn_right=VK_D
input.p2.btn_a=VK_G
input.p2.btn_b=VK_F
input.p2.btn_start=VK_T
input.p2.btn_select=VK_R

Features

• Systems: full DMG and CGB emulation, plus Super Game

Boy borders and palettes.

• Hardware-focused accuracy: a cycle-stepped CPU and high-accuracy PPU, APU,

timer, DMA, serial, and infrared behavior.

• Everyday play: battery-backed saves, ten save-state slots, pause/reset,

hold-to-rewind, recent ROMs, and ZIP/7z archive loading.

• Rollback netplay: TCP multiplayer for link-cable games, with local rollback

hiding normal network latency and synchronized infrared communication.

• Broad cartridge support: MBC1/1M, MBC2, MBC3 with RTC and MBC30, MBC5,

MBC6 with flash, MBC7 with EEPROM/accelerometer, MMM01, HuC1, HuC3, TAMA5,
Pocket Camera, and numerous unlicensed and multicart mappers.

• Accessories: webcam-backed Game Boy Camera, Game Boy Printer with PNG

export, Barcode Boy, Full Changer infrared, Datel Action Replay pass-through,
cartridge rumble, and tilt input.

• Desktop controls and display: keyboard and game-controller input, scaling,

rotation, grayscale, CGB color correction, LCD ghosting, and an SGB-border toggle.

• Cheats: Game Genie and GameShark codes, plus a bundled searchable

libretro cheat database.

Compatibility

Compatibility is a defining feature of Coffee GB. Its test profiles exercise
5,696 automated verdicts from 16 suite families, covering all popular Game
Boy and Game Boy Color test suites, and every verdict passes. Coffee GB also
earns the maximum score in
GBEmulatorShootout.

> Compatibility status: all popular GB/GBC test suites pass, and every
> exact-reference image suite is pixel-perfect: both Acid2 tests,
> CGB-ACID-HELL, Strikethrough, all four CasualPokePlayer tests, and all 24
> Mealybug Tearoom tests.

| Test suite | Cases exercised | Current result |
| --- | ---: | --- |
| Blargg | 54 | 54 / 54 pass* |
| Mooneye Test Suite | 130 | 130 / 130 selected cases pass |
| RTC3Test | 3 | 3 / 3 menus pass |
| SameSuite | 71 | 71 / 71 later-revision cases pass |
| Gambatte HWTests | 4,674 | 4,674 / 4,674 canonical DMG/CGB verdicts match hardware |
| BullyGB | 2 | 2 / 2 DMG and CGB cases pass |
| MBC30Test | 1 | 1 / 1 ROM banking and SRAM case passes |
| GBEmulatorShootout - specific tests | 9 | Maximum score; 8 / 8 images and the ROM+RAM test pass |
| DMG-ACID2 and CGB-ACID2 | 2 | 2 / 2 are pixel-perfect |
| CGB-ACID-HELL | 1 | 1 / 1 is pixel-perfect |
| Strikethrough | 1 | 1 / 1 is pixel-perfect |
| CasualPokePlayer test ROMs | 4 | 4 / 4 are pixel-perfect |
| Mealybug Tearoom | 24 | 24 / 24 are pixel-perfect |
| GBMicrotest | 482 | 482 / 482 machine-readable verdicts pass; 31 additional diagnostics are inventoried but have no automated verdict |
| gbc-hw-tests | 221 | 221 / 221 selected hardware-reference verdicts match exactly |
| Misc.-GB-Tests | 17 | 17 / 17 pass verdicts match |
| Total | 5,696 | 5,696 / 5,696 automated verdicts pass |

• Blargg's aggregate and individual checks overlap by design.

mvn clean test -f core/pom.xml -Ptest-gambatte-hw

mvn test -f core/pom.xml -Ptest-gambatte-hw 
  -Dgambatte.batchCount=64 -Dgambatte.batchIndex=0

AI-assisted compatibility work

Since 2026, Coffee GB has used AI coding agents as compatibility research tools.
A purpose-built <code class="ra0-md-code">controller.Agent</code>
API lets an agent run a ROM headlessly under scripted control, inject input,
capture frames and audio, inspect registers and memory, and disassemble
execution without driving the desktop UI.

The working loop is deliberately evidence-based:

1. Reproduce a reported problem with scripted input and capture the first point

where emulation diverges.

1. Diagnose it against hardware-backed test ROMs, hardware captures, schematics,

and targeted comparisons with reference emulators.

1. Make a focused change, add a regression test where practical, and run the

focused checks; CI runs the full compatibility matrix before merge.

This makes AI useful for exploring difficult timing and cartridge edge cases,
while hardware evidence, automated tests, and maintainer review remain the
standard for correctness.

Project history

Coffee GB began as a six-week deep dive into how a small computer works. The
2017 origin story covers the CPU,
pixel pipeline, audio, early compatibility testing, and first GBC implementation.
The later rollback-netplay article
explains how per-frame snapshots made high-latency link play practical.

| Date | Milestone |
| --- | --- |
| 31 Dec 2016 | The project starts. |
| 14 Jan 2017 | The first playable version runs Tetris, two weeks after the initial commit. |
| 5–7 Feb 2017 | Game Boy Color support lands with double-speed mode, banked RAM/VRAM, color graphics, and the GBC boot path. |
| 22 Dec 2017 | Coffee GB 1.0.0 is released. |
| 29 Feb 2024 | Save-state support is added. |
| Jul 2025 | Fast mementos enable rollback netplay, released in 1.5.0. |
| Aug 2025 | Super Game Boy borders and palettes arrive alongside command support and predefined game palettes. |
| Feb 2026 | The headless agent interface begins the AI-assisted compatibility workflow. |

Architecture

Coffee GB is a Maven reactor with three modules. The dependency flow is
swing → controller → core; the desktop module also uses the core
directly.

| Module | Role | Depends on |
| --- | --- | --- |
| <code class="ra0-md-code">core</code> | Reusable Java emulation engine: CPU, graphics, audio, memory, cartridges, serial/IR, SGB, and peripherals. | — |
| <code class="ra0-md-code">controller</code> | Kotlin orchestration: sessions, timing, save states, rewind, rollback history, and networking. | core |
| <code class="ra0-md-code">swing</code> | Kotlin/Java desktop UI, video/audio/input adapters, webcam and printer integration, and executable-JAR packaging. | controller, core |

The root <code class="ra0-md-code">pom.xml</code> defines the reactor and shared build configuration.

Build from source

Use a JDK 16 or newer and Maven to build. JDK 21
is recommended and is used by CI.

git clone https://github.com/trekawek/coffee-gb.git
cd coffee-gb
mvn clean package

The executable fat JAR is created in swing/target/. On a development snapshot,
run it with:

java -jar swing/target/coffee-gb-*-SNAPSHOT.jar

Kudos

Special thanks to @ScottNash042, whose
thorough compatibility testing, hard-to-find edge-case reports, and thoughtful
feature proposals have provided enormous value to Coffee GB.

Coffee GB also owes a great deal to the Game Boy hardware research community
and to the authors of every test suite linked above.

License

Coffee GB is available under the MIT License.