Game Boy Reborn

A cycle-accurate Nintendo Game Boy (DMG-01) emulator written in modern C++20.
Comes with a complete, extensive and modulable debugger.
Runs on Windows, Linux and macOS.

 
Report a bug or request a feature

Table of Contents

• Overview
• ROM Compatibility
• For Players
  • Controls
  • Save States & Battery Saves
  • Getting ROMs
• For Developers
  • Prerequisites
  • Building
  • Running Tests
  • Project Layout
  • Debugging tools
• Contributing
• License
• References

Overview

Game Boy Reborn aims to emulate the original DMG-01 Game Boy as close as possible. It provides an advanced and extensive debugger.

Current highlights:

• CPU: full SM83 instruction set, verified with the SingleStepTests/sm83 per-opcode test vectors.
• PPU: background, window and sprite (OBJ) rendering to a 160x144 framebuffer.
• APU: all 4 original sound channels (2 pulse, wave, noise) with the frame sequencer and mixer, resampled to 44100 Hz stereo output.
• Save states: quick save/load (Ctrl+S/Ctrl+L) plus save to file/load from file dialogs.
• Rewind: hold R to rewind through several minutes of recent play. The last ~15 seconds are in full detail, older history is progressively coarser (and faster) steps. Release R to resume.
• Battery-backed cartridge RAM: saved next to the ROM as a .sav file.
• Input: keyboard and gamepad (Xbox-style layout) support.
• Adjustable emulation speed: from 0.125x up to 8x.
• Full built-in debugger: a single Debugger window with everything you need to test and dissect any ROM:
  • Execution controls (pause/resume, step one instruction or one frame)
  • Address breakpoints that pause the emulator when the PC reaches them.
  • Live panels for CPU/PPU registers, disassembly, stack, cartridge info, tile data, objects (sprites), background & window tilemaps, APU, a full memory hex viewer (0x0000–0xFFFF), and the log.

ROM Compatibility

The emulator targets original DMG cartridges. Game Boy Color-only titles are not supported, but Game Boy / GBC dual-mode cartridges run in their DMG mode.

Compatibility depends on the cartridge's Memory Bank Controller (MBC), declared in its header:

Cartridge type (header byte)	Mapper	Status
0x00	ROM ONLY	✅ Supported
0x01–0x03	MBC1 (+RAM, +Battery)	✅ Supported
0x05–0x06	MBC2 (+Battery)	✅ Supported
0x08–0x09	ROM+RAM (+Battery)	✅ Supported
0x0F–0x13	MBC3 (+Timer, +RAM, +Battery)	✅ Supported
0x19–0x1E	MBC5 (+RAM, +Rumble, +Battery)	✅ Supported
0x0B–0x0D	MMM01 (+RAM, +Battery)	❌ Not supported
0x20	MBC6	❌ Not supported
0x22	MBC7 (+Sensor, +Rumble, +RAM, +Battery)	❌ Not supported
0xFE–0xFF	HuC3 / HuC1	❌ Not supported

The detected cartridge type, ROM/RAM size and licensee are shown in the Cartridge Info panel window (Debug > Debugger), which is the quickest way to check why a given ROM refuses to load.

For Players

Controls

Game Boy	Keyboard	Gamepad (Xbox layout)
D-Pad	Arrow keys	Left stick / D-Pad
A	Enter	Button A
B	Backspace	Button B
Start	Escape	Start
Select	Tab	Back/Select

Other shortcuts:

Key	Action
F1	Show/hide the menu bar
F11	Toggle fullscreen
F5	Pause/resume emulation
+ / - (numpad)	Cycle through speed presets (0.125x to 8x)
=	Reset speed to 1x
Shift	While pressed, multiply speed by 2
Ctrl+S	Quick-save state
Ctrl+L	Quick-load state
R	While pressed, rewind emulation

Shortcuts for developers are listed under Debugging tools.

Save States & Battery Saves

• Save states snapshot the entire emulator so you can resume later. Use Ctrl+S/Ctrl+L for a quick slot, or File > Save State As... / File > Load State... to pick a file.
• Rewind: hold R to play the game backwards through recent history (roughly the last 6 minutes), then release R to resume play. Rewind takes a lightweight in-memory snapshot every few frames and keeps them at multiple resolutions: the most recent ~15 seconds are stored in full detail, while older history is thinned into progressively coarser steps. It can be toggled on and off from the Emulation > Rewind menu.
• Battery saves: for cartridges with battery-backed RAM (most games that save progress on real hardware), the RAM is automatically written to a .sav file next to the ROM when the ROM changes or the emulator closes, and reloaded the next time you open that ROM.

Getting ROMs

Game Boy Reborn does not ship with, host, or link to any ROM files. To use the emulator you need your own legally-obtained ROM dumps. The roms/ folder in this repository is for local testing only.

For Developers

Prerequisites

• CMake 3.28+

• A C++20 compiler:

  • Windows: MSVC (Visual Studio 2022 or later, with the "Desktop development with C++" workload)
  • Linux: GCC or Clang
  • macOS: Clang (Xcode command-line tools)

• Linux only: SFML is built from source and needs the system X11, OpenGL and udev development packages. For example, on Debian/Ubuntu:

  sudo apt-get install libgl1-mesa-dev libx11-dev libxrandr-dev libxcursor-dev libxi-dev libudev-dev

  SFML's other dependencies (FreeType, HarfBuzz, Ogg/Vorbis/FLAC) are built from source automatically, and macOS and Windows pull the equivalent system libraries automatically.

All other dependencies are fetched automatically by CMake's FetchContent, there is nothing to install manually:

Dependency	Purpose
SFML 3.1.0	Window, input and audio output (Network module disabled, unused)
Dear ImGui + imgui-sfml	Debug UI widgets
ImGuiFileDialog	ROM / save-state file pickers
imgui_club (imgui_memory_editor)	Hex viewer widget for the Memory Viewer debug tool
doctest + nlohmann/json	Unit test framework (test target only)
SingleStepTests/sm83	External per-opcode CPU test vectors (test target only, build directory only)

Building

git clone https://github.com/torresflo/Game-Boy-Reborn.git
cd Game-Boy-Reborn
cmake -B build
cmake --build build --config Release

The first configure step will download all dependencies above, which can take a while. The resulting executable is Game-Boy-Reborn (built from src/main.cpp). The emulation logic and UI also build as the GameBoyCore and GameBoyUI static libraries respectively.

Useful CMake options (pass with -D<option>=<value> at configure time):

Option	Default	Description
GBR_ENABLE_JSON_CPU_TESTS	ON	Fetch and run the SingleStepTests/sm83 CPU test vectors
GBR_JSON_CPU_TEST_CASE_LIMIT	100	Max test cases run per opcode JSON file (each file has 1000)

Running Tests

Building the project also builds the Game-Boy-Reborn-Tests executable. Run the full suite via CTest from the build directory:

ctest --test-dir build

Project Layout

src/
  Core/   GameBoyCore   > emulation only (CPU, PPU, APU, memory bus, cartridge/MBCs)
  UI/     GameBoyUI     > SFML window, input and Dear ImGui debug widgets, links GameBoyCore
  main.cpp              > entry point, constructs the Application and run it
tests/                  > unit tests linked against GameBoyCore only
docs/                   > hardware reference docs

Debugging tools

Game Boy Reborn ships with a full debugger so you can run any ROM under inspection: halt execution wherever you want, set address breakpoints, step forward one instruction or one whole frame at a time, and watch every part of the emulated hardware update live as you go.

All debug panels are shown together in a single window, opened from Debug > Debugger, docked in a default arrangement that you can freely drag, resize, or re-tab (the layout is remembered between sessions):

Panel	Description
Breakpoints	Execution controls (run/pause, step one instruction, step one frame) and a list of address breakpoints that pause the emulator when the PC reaches them. Also toggleable by clicking a line in the Disassembly panel
Cartridge Info	ROM/RAM size, MBC type and licensee
CPU Registers	Live view of all CPU registers, flags, IME, halt state, and cycle count
Stack	Live view of the stack contents around the current stack pointer (SP)
Disassembly	Scrollable list of upcoming instructions starting at the current PC, with a red marker on any line that has a breakpoint
Tile Data	Visual grid of all tiles currently in VRAM
Objects (sprites)	State of the 40 OAM sprite objects
Background & Window Map	Full 256×256 BG or Window tilemap with a viewport overlay (SCX/SCY) and scroll/position register readouts
APU Viewer	Live state of all 4 sound channels (duty/envelope/sweep/wave RAM/LFSR) and the NR50/NR51/NR52 mixer
Memory Viewer	Hex viewer for the full 0x0000–0xFFFF address space
Log	Scrollable log output with level filtering

The execution controls are also bound to global keyboard shortcuts (using the same keys as Visual Studio), so you can step through a ROM without leaving the game window:

Key	Action
F5	Pause/resume emulation (Continue)
F6	Step one frame
F9	Toggle a breakpoint at the current PC
F10	Step one instruction

Contributing

Contributions are what make the open source community such an amazing place to be, learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the GNU General Public License v3.0. See LICENSE for more information.

References

Hardware references used while building this emulator:

• Pan Docs, a comprehensive Game Boy hardware reference
• Game Boy CPU opcode table
• Official Nintendo Game Boy Programming Manual
• The Cycle-Accurate Game Boy Docs
• Game Boy CPU Technical Reference (gbctr)
• SingleStepTests/sm83, per-opcode CPU test vectors used by the test suite
• Low Level Devel - Gameboy Emulator Tutorials