https://github.com/akelsh/mono-gb

A relatively cycle-accurate Gameboy color emulator built in modern C++
https://github.com/akelsh/mono-gb

cplusplus cpp cpu educational emulator gameboy hardware-emulation low-level nintendo retro

Last synced: 5 months ago
JSON representation

A relatively cycle-accurate Gameboy color emulator built in modern C++

Host: GitHub
URL: https://github.com/akelsh/mono-gb
Owner: akelsh
License: mit
Created: 2025-12-10T18:27:55.000Z (7 months ago)
Default Branch: main
Last Pushed: 2026-01-26T13:04:27.000Z (5 months ago)
Last Synced: 2026-01-26T13:09:01.338Z (5 months ago)
Topics: cplusplus, cpp, cpu, educational, emulator, gameboy, hardware-emulation, low-level, nintendo, retro
Language: C++
Homepage:
Size: 10.4 MB
Stars: 1
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

          # Mono-GB

![Gameboy Games Showcase](assets/showcase.gif)

Mono-GB is a relatively cycle-accurate Gameboy color emulator built in modern C++. Despite the name, the emulator

fully supports both DMG and CGB games in full color.

This is a hobby project with the main goal being to understand the intricacies of low-level system design.

## Features

The following is a list of fully implemented features:

- Backwards compatibility with the original Gameboy.

- Machine Cycle accurate CPU.

- Dual-speed support

- Support for MBC1, MBC2, MBC3, and MBC5.

- DMG colorization.

- Dot accurate PPU sprite & BG pipelines.

- Phase-based instruction execution.

This project is still a work in progress. The following is a list of features I am planning on implementing:

- Audio support.

- T-state based instruction execution.

- A fully functional debugger.

## Tests

The accuracy of a gameboy emulator is usually determined by test ROMs that are created using the real hardware.

The following is a list of the ROM tests that Mono GB passes:

- [Blargg's ROM tests](https://github.com/retrio/gb-test-roms):

    - [cpu_instrs](https://github.com/retrio/gb-test-roms/tree/master/cpu_instrs)

    - [halt_bug](https://github.com/retrio/gb-test-roms/blob/master/halt_bug.gb)

    - [interrupt_time](https://github.com/retrio/gb-test-roms/tree/master/interrupt_time) (Note: Failure is expected on

      CGB)

    - [instr_timing](https://github.com/retrio/gb-test-roms/tree/master/instr_timing)

    - [mem_timing](https://github.com/retrio/gb-test-roms/tree/master/mem_timing)

    - [mem_timing-2](https://github.com/retrio/gb-test-roms/tree/master/mem_timing-2)

- [Mooneye test suite](https://github.com/Gekkio/mooneye-test-suite)

    - [acceptance/add_sp_e_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/add_sp_e_timing.s)

    - [acceptance/call_cc_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/call_cc_timing.s)

    - [acceptance/call_cc_timing2](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/call_cc_timing2.s)

    - [acceptance/call_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/call_timing.s)

    - [acceptance/call_timing2](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/call_timing2.s)

    - [acceptance/div_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/div_timing.s)

    - [acceptance/ei_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/ei_timing.s)

    - [acceptance/halt_ime0_ei](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/halt_ime0_ei.s)

    - [acceptance/if_ie_registers](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/if_ie_registers.s)

    - [acceptance/if_ie_registers](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/if_ie_registers.s)

    - [acceptance/intr_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/intr_timing.s)

    - [acceptance/jp_cc_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/jp_cc_timing.s)

    - [acceptance/jp_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/jp_timing.s)

    - [acceptance/ld_hl_sp_e_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/ld_hl_sp_e_timing.s)

    - [acceptance/oam_dma_restart](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/oam_dma_restart.s)

    - [acceptance/oam_dma_start](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/oam_dma_start.s)

    - [acceptance/oam_dma_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/oam_dma_timing.s)

    - [acceptance/pop_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/pop_timing.s)

    - [acceptance/push_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/push_timing.s)

    - [acceptance/ret_cc_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/ret_cc_timing.s)

    - [acceptance/ret_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/ret_timing.s)

    - [acceptance/reti_intr_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/reti_intr_timing.s)

    - [acceptance/reti_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/reti_timing.s)

    - [acceptance/rst_timing](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/rst_timing.s)

    - [acceptance/bits/mem_oam](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/bits/mem_oam.s)

    - [acceptance/bits/reg_f](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/bits/reg_f.s)

    - [acceptance/instr](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/instr)

    - [acceptance/interrupts](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/interrupts)

    - [acceptance/oam_dma/basic](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/oam_dma/basic.s)

    - [acceptance/oam_dma/reg_read](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/oam_dma/reg_read.s)

    - [acceptance/timer](https://github.com/Gekkio/mooneye-test-suite/blob/main/acceptance/timer)

    - [acceptance/emulator-only/mbc1](https://github.com/Gekkio/mooneye-test-suite/blob/main/emulator-only/mbc1)

    - [acceptance/emulator-only/mbc2](https://github.com/Gekkio/mooneye-test-suite/blob/main/emulator-only/mbc2)

    - [acceptance/emulator-only/mbc5](https://github.com/Gekkio/mooneye-test-suite/blob/main/emulator-only/mbc5)

- [rtc3-test](https://github.com/aaaaaa123456789/rtc3test)

- [cgb-acid-2](https://github.com/mattcurrie/cgb-acid2)

- [dmg-acid-2](https://github.com/mattcurrie/dmg-acid2)

- [cgb-acid-hell](https://github.com/mattcurrie/cgb-acid-hell)

## Build

Mono-GB uses CMake presets for building. Ensure you have CMake (3.21+), Ninja, and a C++23 compatible compiler

installed.

### Unix-like (Linux/macOS)

To build for release:

```bash

# Configure the project

cmake --preset unixlike-gcc-release

# Build the project

cmake --build out/build/unixlike-gcc-release

```

### Windows (MSVC)

To build for release:

```bash

# Configure the project

cmake --preset windows-msvc-release-user-mode

# Build the project

cmake --build out/build/windows-msvc-release-user-mode

```

## Running

After building, the executable can be found in the `src` directory within the build folder.

```bash

# Unix-like

./out/build/unixlike-gcc-release/src/mono_gb

# Windows

./out/build/windows-msvc-release-user-mode/src/RelWithDebInfo/mono_gb.exe

```

## Credits

Resources:

- [Gameboy Pandocs](https://gbdev.io/pandocs/)

- [Game Boy: Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf)

Showcase Games:

- [FEED IT SOULS](https://gumpyfunction.itch.io/feed-it-souls)

- [Taiyaki Fabulous Museum of Fishes](https://objetdiscret.itch.io/tai-fab-museum)

Tests:

- [Blargg's ROM tests](https://github.com/retrio/gb-test-roms)

- [Mooneye test suite](https://github.com/Gekkio/mooneye-test-suite)

- [rtc3-test](https://github.com/aaaaaa123456789/rtc3test)

- [cgb-acid-2](https://github.com/mattcurrie/cgb-acid2)

- [dmg-acid-2](https://github.com/mattcurrie/dmg-acid2)

- [cgb-acid-hell](https://github.com/mattcurrie/cgb-acid-hell)

- [GameboyCPUTests](https://github.com/adtennant/GameboyCPUTests)

UI

- [Tamzen font](https://github.com/sunaku/tamzen-font)

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/akelsh/mono-gb

Awesome Lists containing this project

README