GoBoy

GoBoy is a multi-platform Nintendo GameBoy and GameBoy Color emulator written in go. The emulator can run the majority of GB games and CGB games. Please feel free to contribute if you’re interested in GameBoy emulator development.

The program includes debugging functions making it useful for understanding the emulator operation for building one yourself. These functions include printing of opcodes and register values to the console at each step (although will greatly slow down the emulation) and toggling of individual sound channels.

Installation

Download the latest release of GoBoy from the releases page.

Building from source

GoBoy requires Go 1.25 or later. With Go installed, you can install GoBoy into your go bin by running:

go install github.com/Humpheh/goboy/cmd/goboy@latest

Or build it from a clone of the repository:

git clone https://github.com/Humpheh/goboy.git
cd goboy
go build -o goboy ./cmd/goboy

GoBoy is compatible with macOS, Windows and Linux. It uses Ebitengine for graphics and input, and Oto for sound.

Thanks to Ebitengines support, GoBoy can run on these platforms with no cgo required:

Windows
macOS
Linux
WebAssembly
FreeBSD

See the Ebitengine install guide for other platforms including Android, iOS, Nintendo Switch and Xbox.

Usage

goboy zelda.gb

Controls: ← ↑ ↓ → Z X Enter Backspace

Hold Tab to fast-forward at 2x speed, and press F to toggle fullscreen.

Other options:

  -dmg
    	set to force dmg mode
  -mute
    	mute sound output

Debug or experimental options:

  -debug
    	enable debug functionality on startup
  -cpuprofile string
    	write cpu profile to file (debugging)
  -disableVsync
    	set to disable vsync (debugging)
  -stepthrough
    	step through opcodes (debugging)
  -unlocked
    	if to unlock the cpu speed (debugging)

Debugging

There are a few keyboard shortcuts useful for debugging. They are only active while debug functionality is enabled, which can be toggled with \ or turned on at startup with -debug:

Esc - pause/resume emulation
= - cycle the colour palette (DMG mode)
Q - force toggle background
W - force toggle sprites
D - print background map to log
E - toggle opcode printing to console (will slow down execution)
7,8,9,0 - toggle sound channels 1 through 4.

Saving

If the loaded rom supports a battery a <rom-name>.sav (e.g. zelda.gb.sav) file will be created next to the loaded rom containing a dump of the RAM from the cartridge. A loop in the program will update this save file every second while the game is running.

Tests

GoBoy currently passes Blargg’s cpu_instrs, instr_timing, mem_timing and interrupt_time test roms, and Mooneye’s sprite_priority test.

These roms are included in the source code under roms/ along with tests in pkg/gb that check the output is as expected. Run them with go test ./...; they are also run by GitHub Actions on each commit.

Contributing

Please feel free to open pull requests to this project or play around if you’re interested! There are still plenty of small bugs that can easily be found through playing games on the emulator, or take a task from the TODO list below!

Known Bugs and TODO list

Resources

A large variety of resources were used to understand and test the GameBoy hardware. Some of these include: