tetromino

README

Welcome to Tetromino

Tetromino is a Game Boy emulator written in Go.

Tetris

Super Mario Land

Pokemon Red

Debugging the LCD

Tetromino has some fun LCD debugging that uses colour to differentiate sprites (in blue) from background (white when on-screen and red when off-screen) to show how scrolling is implemented.

Building and Running

Build Tetromino like this. You may need to install some OS-specific packages to support video and sound - see below for details.

go build

To run, you'll need a ROM file which you can specify like this:

tetromino tetris.gb

Other options exist including enabling debug. List them like this:

tetromino --help

Flags must be specified before the ROM filename e.g.

tetromino --debuglcd /roms/tetris.gb

Controls

Arrows keys : Up/Down/Left/Right A : Start S : Select Z : B button X : A button T : Take screenshot

Tests

Tetromino has accurate CPU, timer, sound and MBC1 implementations (though no support for other MBCs).

Blargg Tests

All Blargg tests pass.

Result	Blargg test	Screenshot
💚 pass	cpu_instrs/cpu_instrs.gb	pic
💚 pass	dmg_sound/dmg_sound.gb	pic
💚 pass	halt_bug.gb	pic
💚 pass	instr_timing/instr_timing.gb	pic
💚 pass	mem_timing/mem_timing.gb	pic
💚 pass	mem_timing-2/mem_timing.gb	pic
💚 pass	oam_bug/oam_bug.gb	pic

Mooneye Tests

Some Mooneye tests pass (65 of 94).

Result	Mooneye test	Screenshot
💚 pass	acceptance/add_sp_e_timing.gb	pic
💚 pass	acceptance/bits/mem_oam.gb	pic
💚 pass	acceptance/bits/reg_f.gb	pic
💚 pass	acceptance/bits/unused_hwio-GS.gb	pic
💚 pass	acceptance/boot_div-dmgABCmgb.gb	pic
💚 pass	acceptance/boot_regs-dmgABC.gb	pic
💚 pass	acceptance/call_cc_timing.gb	pic
💚 pass	acceptance/call_timing.gb	pic
💚 pass	acceptance/div_timing.gb	pic
💚 pass	acceptance/halt_ime0_ei.gb	pic
💚 pass	acceptance/halt_ime0_nointr_timing.gb	pic
💚 pass	acceptance/halt_ime1_timing.gb	pic
💚 pass	acceptance/if_ie_registers.gb	pic
💚 pass	acceptance/instr/daa.gb	pic
💚 pass	acceptance/intr_timing.gb	pic
💚 pass	acceptance/jp_cc_timing.gb	pic
💚 pass	acceptance/jp_timing.gb	pic
💚 pass	acceptance/oam_dma_restart.gb	pic
💚 pass	acceptance/oam_dma_timing.gb	pic
💚 pass	acceptance/oam_dma/basic.gb	pic
💚 pass	acceptance/oam_dma/reg_read.gb	pic
💚 pass	acceptance/pop_timing.gb	pic
💚 pass	acceptance/ret_cc_timing.gb	pic
💚 pass	acceptance/ret_timing.gb	pic
💚 pass	acceptance/reti_timing.gb	pic
💚 pass	acceptance/timer/div_write.gb	pic
💚 pass	acceptance/timer/rapid_toggle.gb	pic
💚 pass	acceptance/timer/tim00_div_trigger.gb	pic
💚 pass	acceptance/timer/tim00.gb	pic
💚 pass	acceptance/timer/tim01_div_trigger.gb	pic
💚 pass	acceptance/timer/tim01.gb	pic
💚 pass	acceptance/timer/tim10_div_trigger.gb	pic
💚 pass	acceptance/timer/tim10.gb	pic
💚 pass	acceptance/timer/tim11_div_trigger.gb	pic
💚 pass	acceptance/timer/tim11.gb	pic
💚 pass	acceptance/timer/tima_reload.gb	pic
💚 pass	acceptance/timer/tima_write_reloading.gb	pic
💚 pass	acceptance/timer/tma_write_reloading.gb	pic
💚 pass	emulator-only/mbc1/bits_bank1.gb	pic
💚 pass	emulator-only/mbc1/bits_bank2.gb	pic
💚 pass	emulator-only/mbc1/bits_mode.gb	pic
💚 pass	emulator-only/mbc1/bits_ramg.gb	pic
💚 pass	emulator-only/mbc1/ram_256kb.gb	pic
💚 pass	emulator-only/mbc1/ram_64kb.gb	pic
💚 pass	emulator-only/mbc1/rom_16Mb.gb	pic
💚 pass	emulator-only/mbc1/rom_1Mb.gb	pic
💚 pass	emulator-only/mbc1/rom_2Mb.gb	pic
💚 pass	emulator-only/mbc1/rom_4Mb.gb	pic
💚 pass	emulator-only/mbc1/rom_512kb.gb	pic
💚 pass	emulator-only/mbc1/rom_8Mb.gb	pic
💚 pass	emulator-only/mbc2/bits_ramg.gb	pic
💚 pass	emulator-only/mbc2/bits_romb.gb	pic
💚 pass	emulator-only/mbc2/bits_unused.gb	pic
💚 pass	emulator-only/mbc2/ram.gb	pic
💚 pass	emulator-only/mbc2/rom_1Mb.gb	pic
💚 pass	emulator-only/mbc2/rom_2Mb.gb	pic
💚 pass	emulator-only/mbc2/rom_512kb.gb	pic
💚 pass	emulator-only/mbc5/rom_16Mb.gb	pic
💚 pass	emulator-only/mbc5/rom_1Mb.gb	pic
💚 pass	emulator-only/mbc5/rom_2Mb.gb	pic
💚 pass	emulator-only/mbc5/rom_32Mb.gb	pic
💚 pass	emulator-only/mbc5/rom_4Mb.gb	pic
💚 pass	emulator-only/mbc5/rom_512kb.gb	pic
💚 pass	emulator-only/mbc5/rom_64Mb.gb	pic
💚 pass	emulator-only/mbc5/rom_8Mb.gb	pic

Dependencies

Tetromino uses GLFW for video and PortAudio for sound so you might need to install some OS-specific packages.

GLFW

• GLFW C library source is included and built automatically as part of the Go package. But you need to make sure you have dependencies of GLFW:
  • On macOS, you need Xcode or Command Line Tools for Xcode (xcode-select --install) for required headers and libraries.
  • On Ubuntu/Debian-like Linux distributions, you need libgl1-mesa-dev and xorg-dev packages.
  • On CentOS/Fedora-like Linux distributions, you need libX11-devel libXcursor-devel libXrandr-devel libXinerama-devel mesa-libGL-devel libXi-devel packages.

See this page if those instructions don't work for you.

PortAudio

On macOS: brew install portaudio

References and Thanks

You can find a huge amount of great information about the Game Boy out there and many people have shared their work for others to build on. Thanks to everyone who has shared their experiences, code and documentation.

Incredible test roms from:

• blargg
• Gekkio (https://github.com/Gekkio/mooneye-gb)

These resources have been invaluable for me:

• http://marc.rawer.de/Gameboy/Docs/GBCPUman.pdf
• http://bgb.bircd.org/pandocs.htm
• http://cturt.github.io/cinoop.html
• https://github.com/fogleman/nes
• http://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html
• https://github.com/lmmendes/game-boy-opcodes