# GoBoy: a Game Boy and Game Boy Color emulator in Go, built as a learning exercise

> GoBoy runs most DMG games and some CGB titles, ships debugger shortcuts that make the internals visible, and passes Blargg's cpu_instrs and instr_timing test ROMs. It is also honest about being unfinished, and the TODO list is the most useful part of the README.

**Humpheh/goboy** — Multi-platform Nintendo Game Boy Color emulator written in Go

- Repository: https://github.com/Humpheh/goboy
- Website: https://humpheh.github.io/goboy/
- Stars: 2,639 · Forks: 119
- Language: Go
- License: MIT
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/humpheh-goboy

## What GoBoy is, and the problem it actually solves

GoBoy is a Nintendo Game Boy and Game Boy Color emulator written in Go, distributed under the MIT licence. It targets macOS, Windows and Linux. The README is direct about its purpose: it was primarily built as a development exercise and remains work in progress.

That framing matters when you decide whether to adopt it. The audience is not someone who wants a polished handheld experience. It is someone who wants to read a Go implementation of the Sharp LR35902, the PPU and the APU, run it, and watch what happens. The debugging features are the product: printing opcodes and register values at each step, toggling individual sound channels, dumping palette and background map data. The README notes that opcode printing will greatly slow down emulation, which tells you the feature is meant for inspection, not for play.

The second audience is anyone learning Go who wants a project with a real specification behind it. Game Boy hardware behaviour is documented by third parties, and GoBoy's README lists the references it used, including the Pan Docs PDF, gb-test-roms, and coffee-gb. A codebase that cites its sources is easier to check against the hardware documentation than one that does not.

## How the emulator is put together

The repository layout separates the machine from the front end. The cmd/ directory holds the goboy entry point, while package/ and pkg/ hold the emulator itself. The go.mod file names the module as github.com/Humpheh/goboy and pins the rendering and audio dependencies: github.com/gopxl/pixel/v2 for graphics and input binding, and github.com/hajimehoshi/oto for sound. OpenGL arrives indirectly through go-gl/gl and glfw.

That split has a practical consequence. The emulation core does not depend on pixel directly, so the CPU and PPU can be exercised from tests without opening a window. The README confirms this is how the project checks itself: Blargg's cpu_instrs and instr_timing ROMs are included in the source along with instructions_test.go and timing_test.go, and the README states these run on each commit. The repository also carries a .travis.yml, so the original continuous integration configuration is Travis.

Sound is where the architecture shows its age in the dependency list. oto is a low-level audio library, and the TODO list still carries better APU buffering and minor APU timing issues as open items. The README points at the Pokemon Yellow opening screen as the reason the APU was reworked at all, which is a useful hint about where audio correctness is hardest to reach.

## Installing GoBoy and running a first ROM

The README offers two paths. The first is to download the latest release binary from the releases page. The second is to build from source, which is what you want if you intend to read or modify the code.

The simplest source install uses go get, which places the binary in your Go bin directory:

```bash
go get github.com/Humpheh/goboy/cmd/goboy
```

If you are on Go 1.11 or later, the README also gives a clone-and-build route. Note that the go.mod in the repository declares go 1.23.0 with toolchain go1.24.5, so a modern Go toolchain is what the current tree expects:

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

Building on Windows 10 requires MinGW, and on Linux you need gtk installed. Because pixel requires OpenGL, the README points at the pixel project's requirements page for the platform-specific packages you may still be missing.

Once built, running a ROM is a single argument. The README gives this exact example:

```bash
goboy zelda.gb
```

The controls are the arrow keys for the d-pad, Z and X for the two action buttons, Enter for Start and Backspace for Select. In DMG mode the colour palette cycles with the = key, and F toggles fullscreen. Two flags are documented as normal options: -dmg forces DMG mode, and -mute disables sound output. Everything else in the flag list is grouped under debug or experimental options, including -stepthrough, -disableVsync, -unlocked and -cpuprofile, and the README labels them as debugging aids rather than user features.

## The debugger shortcuts are the reason to pick this over a faster emulator

Most emulator projects treat debugging as an afterthought. GoBoy inverts that. A set of keyboard shortcuts exposes internal state while a game runs: Q forces the background on or off, W does the same for sprites, A prints Game Boy Color background palette data, S prints sprite palette data, and D dumps the background map to the log. E toggles opcode printing to the console, and the README warns plainly that this will slow down execution. The number keys 7, 8, 9 and 0 toggle sound channels one through four.

For someone writing their own emulator, this is a working reference implementation you can interrogate. Toggle sprites off and the background rendering becomes visible on its own. Dump the background map and compare it against what you think the tile map should contain. Isolate a single sound channel to hear what that channel contributes. None of this requires a debugger build or a special ROM.

The same honesty applies to the bug list. The README's TODO section shows checked-off items such as sprite edge drawing, the Pokemon Red splash screen background offset, MBC3 banking support, and STOP opcode behaviour. Still open are sprite Z-drawing bugs, APU timing and buffering, jitter, MBC3 clock support, CPU and PPU speed, save-states, and boot ROM support. A project that publishes its open defects this specifically is easier to trust than one that does not, and it tells you exactly which games to avoid.

## Saving, and what happens when a cartridge uses a battery

Save handling is deliberately simple. If the loaded ROM supports a battery, GoBoy writes a file named after the ROM with a .sav extension next to it. The README gives zelda.gb.sav as the example. A loop in the program updates that file every second while the game runs.

Two consequences follow. First, the save file is a dump of the cartridge RAM, not an emulator-specific snapshot format, so it lives beside your ROM and travels with it. Second, because the write happens on a one-second loop, a hard kill of the process can lose up to a second of progress. That is a reasonable trade for a project at this stage, but it is a real boundary.

Save-states are a different feature, and they are not implemented. The TODO list carries support save-states as an open item. If your workflow depends on snapshotting at an exact frame, GoBoy is the wrong tool today, and the README does not document any rollback or snapshot mechanism to fall back on.

## Where GoBoy falls short, and what to use instead

The README states the emulator can run the majority of GB games and some CGB games. That word some is doing real work. Game Boy Color support is partial, and the open TODO items around sprite Z-drawing, APU timing and MBC3 clock support are exactly the areas where CGB-era cartridges and real-time-clock games tend to break. If your goal is to play a specific Game Boy Color title, this is not the project to bet on without testing that title first.

Performance is also on the open list. Speed up CPU and PPU has not been checked off, so frame pacing on slower hardware is not something the README claims. The -unlocked flag exists, but it is filed under debugging, not as a performance option.

For a different approach, consider SameBoy or BGB. BGB is named in GoBoy's own resources section as invaluable for debugging, which is a fair signal about where it sits: it is a mature, accuracy-focused emulator with a long track record, and it is not written in Go. SameBoy takes a similar accuracy-first stance and is widely used as a reference for hardware behaviour. The difference in approach is the point. GoBoy optimizes for a readable Go implementation you can modify and step through. BGB and SameBoy optimize for getting the hardware behaviour right first. If you want to play, pick the accuracy-focused tools. If you want to understand or extend an emulator in Go, GoBoy is the more useful starting point.

## Maintenance, releases and licence

The repository is not archived, and its last push was on 2026-03-30. That is recent enough that the tree reflects current Go tooling: go.mod declares go 1.23.0 and toolchain go1.24.5, and the dependencies include gopxl/pixel/v2 v2.3.0 rather than the older faiface/pixel that the README text still references. The README and the module file disagree on that point, and the module file is the one that governs what actually builds.

Release cadence is slow. The most recent tagged release is v0.5 from 2020-08-09, preceded by v0.4.2 in 2018 and v0.3 earlier in 2018. Anyone installing from the releases page is getting a binary from 2020, while the source tree has moved on since. Building from source is the way to get the current code.

The licence is MIT, which is permissive and permits commercial use and modification provided the copyright notice and permission notice are retained. That is a summary of the licence text, not legal advice; read the LICENSE file in the repository if the distinction matters to your organisation. The practical implication for a fork is that you can vendor GoBoy into a larger project, but you inherit the open TODO list along with it.

## Conclusion

Adopt GoBoy if you want a readable Go codebase for studying Game Boy hardware behaviour, or a small emulator you can step through opcode by opcode. Do not adopt it as a daily driver for a full library: the README states it runs the majority of GB games and some CGB games, and save-states, boot ROM support and MBC3 clock support are still unchecked on the TODO list. Before relying on it for a specific cartridge, verify that the mapper it uses is supported and that the battery save file appears next to the ROM after a second of play.

## FAQ

### What is a GoBoy?

GoBoy is a multi-platform Nintendo Game Boy and Game Boy Color emulator written in Go. The README describes it as primarily built as a development exercise and still work in progress, with debugging functions intended to help people understand emulator operation.

### Which platforms does GoBoy support?

The README states GoBoy is compatible with macOS, Windows and Linux. Building on Windows 10 requires MinGW, and on Linux you need gtk installed, with additional OpenGL requirements listed on the pixel project's readme.

### How do I install GoBoy?

You can download the latest release from the releases page, or build from source with go get github.com/Humpheh/goboy/cmd/goboy. The README also gives a git clone and go build route for Go 1.11 and later.

### Does GoBoy support save-states?

No. Support save-states appears as an unchecked item on the README's TODO list. Battery-backed cartridges do get a .sav file written next to the ROM and updated every second while the game runs.

### Can GoBoy run Game Boy Color games?

Partially. The README says the emulator can run the majority of GB games and some CGB games, and colour support is present. Open TODO items include sprite Z-drawing bugs and MBC3 clock support, which affect some CGB-era behaviour.

## Sources

- [Humpheh/goboy on GitHub](https://github.com/Humpheh/goboy)
- [License: MIT](https://github.com/Humpheh/goboy/blob/master/LICENSE)
- [Project website](https://humpheh.github.io/goboy/)
- [README](https://github.com/Humpheh/goboy/blob/master/README.md)
- [Releases](https://github.com/Humpheh/goboy/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/humpheh-goboy