Coffee GB

Coffee GB is a Gameboy Color emulator written in Java 16 (core) and Kotlin (UI). It's meant to be a development exercise. More info can be found in the blog post Why did I spend 1.5 months creating a Gameboy emulator?

Building

The emulator can be build with Maven:

mvn clean package

The coffee-gb-*.jar executable file will be available in the ./swing/target directory.

Usage

1. Download the most recent release.
2. Double-click the JAR or launch it with java -jar coffee-gb-*.jar command.
3. Load a game.

Play with ←, ↑, ↓, →, Z, X, Enter, Backspace.

Features

• Full support for GB & GBC emulation.
• Partial Super Gameboy emulation (borders and palette).
• Cycle-exact CPU emulation. Each opcode is split into a few micro-operations (load value from memory, store it to register, etc.) and each micro-operation is run in a separate CPU cycle.
• Quite compatible (all the Blargg's tests are passed, although some game still doesn't work)
• Rollback-based netplay
• MBC1-5 support
• Battery saves
• Support for zipped ROMs
• ROM-based compatibility tests run from Maven

Modules

Emulator is split into modules:

• core - the core emulator. This module can be easily referenced from other projects.
• swing - the desktop UI with executable.
• controller - the middleware between the UI and the core. It also contains network support.

Running Blargg's tests

The Blargg's test ROMs are used for testing the compatibility. Tests can be launched from Maven using appropriate profile:

mvn clean test -f core/pom.xml -Ptest-blargg
mvn clean test -f core/pom.xml -Ptest-blargg-individual # for running "single" tests providing more diagnostic info

They are also part of the Travis-based CI.

The tests output (normally displayed on the Gameboy screen) is redirected to the stdout:

cpu_instrs

01:ok  02:ok  03:ok  04:ok  05:ok  06:ok  07:ok  08:ok  09:ok  10:ok  11:ok

Passed all tests

Coffee GB passes all the tests:

• cgb_sound
• cpu_instrs
• dmg_sound-2
• halt_bug
• instr_timing
• interrupt_time
• mem_timing-2
• oam_bug-2

Mooneye tests

The Mooneye GB emulator comes with a great set of test ROMs. They can be used to test the Coffee GB as well. Use -Ptest-mooneye profile:

mvn clean test -f core/pom.xml -Ptest-mooneye

Screenshots

Key bindings

The default key bindings can be changed with the ~/.coffeegb.properties file. The file has following format:

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_BACK_SPACE

The key list can be found in the KeyEvent JavaDoc.

Resources

• GameBoy CPU manual
• The Ultimate GameBoy talk
• Gameboy opcodes
• Nitty Gritty Gameboy cycle timing
• Video Timing
• BGB emulator --- good for testing / debugging, works fine with Wine
• The Cycle-Accurate Game Boy Docs
• Test ROMs - included in the src/test/resources/roms
• Pandocs
• Mooneye GB - an accurate emulator written in Rust, contains great ROM-based acceptance tests