GoBoy is a multi-platform Nintendo GameBoy and GameBoy Color emulator written in go. The emulator can run the majority of GB games and some CGB games. There is also colour and sound support. This emulator was primarily built as a development exercise and is still work in progress. 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.
Download the latest release of GoBoy from the releases page.
Building from source
With go installed, you can install GoBoy into your go bin by running:
go get github.com/Humpheh/goboy/cmd/goboy
If you have Go 1.11 you can also do:
git clone https://github.com/Humpheh/goboy.git cd goboy go build -o goboy cmd/goboy/main.go
GoBoy is compatible with MacOS, Windows and Linux. Building on Windows 10 requires MinGW and on Linux, you'll need to install gtk.
Controls: ← ↑ ↓ → Z X Enter Backspace
The colour palette can be cycled with = (in DMG mode), and the game can be made fullscreen with F.
-dmg set to force dmg mode -mute mute sound output
Debug or experimental options:
-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)
There are a few keyboard shortcuts useful for debugging:
Q - force toggle background
W - force toggle sprites
A - print gb background palette data (cgb)
S - print sprite palette data (cgb)
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.
If the loaded rom supports a battery a
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.
GoBoy currently passes all of the tests in Blargg's
instr_timing test roms.
These roms are included in the source code along with a test to check the output is as expected
timing_test.go). These tests are also run on each commit.
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
- Sprite Z-drawing
- Sprites near edge of screen not drawing
- Top half of sprite disappearing off top of screen
- Small sprites row glitch
- BG tile window offset issue - visible on Pokemon Red splash screen - possibly mistimed interrupt?
- Harry Potter and The Chamber of Secrets has odd sprite issues
- Request to set screen to white does not do so
- MBC3 banking support
- Improve APU (see Pokemon Yellow opening screen for reason why)
- MBC3 clock support
- White screen when off
- Speed up CPU and PPU
- Resizable window
- Platform native UI?
- MBC4-7 support (?)
- More DMG colour palettes
- STOP opcode behaviour
- Support save-states (could use gob)
- Support boot roms
- Blargg's test ROMs
A large variety of resources were used to understand and test the GameBoy hardware. Some of these include:
- http://bgb.bircd.org/ - invaluable for debugging