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
   

3. 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 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.

Default controls

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

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 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 treated as a continuously tested feature, not as a static game list. The test profiles exercise 5,721 cases from 13 suite families. Every automated verdict is guarded: exact hardware results are required where Coffee GB matches them, while unresolved Gambatte outputs are pinned against regressions.

Pixel status: both Acid2 references and all 24 Mealybug Tearoom reference images are pixel-perfect.

* 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 controller.Agent 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.
2. Diagnose it against hardware-backed test ROMs, hardware captures, schematics, and targeted comparisons with reference emulators.
3. 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.

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.

The root pom.xml 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.