GrouBoy - a modern C++ Game Boy Color emulator

This is an educational implementation of a Game Boy Color Emulator, developed using modern C++. The primary aim of this project is to provide an implementation that is easy to read, well architecture, with extensive code documentation and testing. It is designed to function seamlessly on Windows, Mac, and Linux.

Features

The following features are implemented:

• Memory abstraction
• All CPU instructions
• PPU abstraction
• GUI
• Sprites
• Inputs
• Timer
• Serial
• Memory Bus Controller
  • MBC1
  • MBC2
  • MBC3
• Sound
  • Channel 1
  • Channel 2
  • Channel 3
  • Channel 4
• GameBoy color rendering

Future work:

• Sub-instruction CPU timing
• FIFO PPU
• Other MBCs
• GBC Double-speed

Input mapping

Keyboard input	Gameboy input
Up Arrow	Up
Down Arrow	Down
Left Arrow	Left
Right Arrow	Right
Enter	Start
Space bar	Select
A	A
B	B

Demo

Name	Output
Pokemon Silver
Zelda
Mario

Dependencies

This project relies on SDL for the GUI, GoogleTest for the testing suite, and spdlog for logging.

Compilation

The project can be compiled using CMake, it will automatically retrieve some dependencies like SDL and GoogleTest.

mkdir -p build && cd build/
cmake ..
cmake --build .

Tests

The emulator is tested using various test suites and automated test cases for all components. You can find the test report in the Github actions.

Blargg's test coverage:

Category	Test Name	Pass/Fail
CPU Instructions	01 - Special	✅
CPU Instructions	02 - Interrupts	✅
CPU Instructions	03 - Op SP, HL	✅
CPU Instructions	04 - Op r,imm	✅
CPU Instructions	05 - Op rp	✅
CPU Instructions	06 - LD r,r	✅
CPU Instructions	07 - JR,JP,Call,RET,RST	✅
CPU Instructions	08 - Misc Instrs	✅
CPU Instructions	09 - Op r,r	✅
CPU Instructions	10 - Bits Ops	✅
CPU Instructions	11 - Op a,(hl)	✅
Instructions Timing	Instr Timing	✅
Sound	01 - Registers	✅
Sound	02 - Len ctr	✅
Sound	03 - Trigger	❌
Sound	04 - Sweep	✅
Sound	05 - Sweep details	❌
Sound	06 - Overflow on trigger	✅
Sound	07 - Len sweep period sync	❌
Sound	08 - Len ctrl during power	❌
Sound	09 - Wave read while on	❌

Acid2 test:

Reference image	Pass/Fail
	✅
	✅

Mooneye test suite:

Category	Test Name	Pass/Fail
CPU Instructions	DAA	✅
Bits	MEM OAM	✅
Bits	Reg F	✅
Bits	unused_hwio-GS	✅
OAM DMA	Basic	✅
Timer	Div Write	✅
Timer	Rapid toggle	❌
Timer	Tim00	✅
Timer	Tim00 Div trigger	❌
Timer	Tim01	✅
Timer	Tim01 Div trigger	❌
Timer	Tim10	✅
Timer	Tim10 Div trigger	❌
Timer	Tim11	✅
Timer	Tim11 Div trigger	❌

Reference

• https://izik1.github.io/gbops/index.html
• https://gbdev.io/pandocs/
• https://gbdev.gg8.se/wiki/articles/Main_Page
• https://archive.org/details/GameBoyProgManVer1.1/mode/2up?view=theater

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT