Gameboy emulator in Java 8.
Switch branches/tags
Clone or download
Latest commit f39cd4d May 28, 2018

Coffee GB

Build Status

Coffee GB is a Gameboy Color emulator written in Java 8. 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?

Coffee GB running game


The emulator can be build with Maven:

mvn clean package

The jar file will be available in the ./target directory.


java -jar coffee-gb.jar [OPTIONS] ROM_FILE

Available options:
  -d  --force-dmg                Emulate classic GB (DMG) for universal ROMs
  -c  --force-cgb                Emulate color GB (CGB) for all ROMs
  -b  --use-bootstrap            Start with the GB bootstrap
  -db --disable-battery-saves    Disable battery saves
      --debug                    Enable debug console
      --headless                 Start in the headless mode

Play with , , , , Z, X, Enter, Backspace.


  • Cycle-exact Gameboy 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)
  • GPU
  • Joypad
  • Timer
  • Sound
  • MBC1-5 support
  • Battery saves
  • Support for zipped ROMs
  • ROM-based compatibility tests run from Maven

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 -Ptest-blargg
mvn clean test -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:


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 -Ptest-mooneye


Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game Coffee GB running game

Key bindings

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


The key list can be found in the KeyEvent JavaDoc.