DocBoy is an open source, accuracy-focused, GameBoy emulator, written in C++17.
It supports emulation of both the original DMG (GameBoy) or CGB (GameBoy Color).
Can be used either with the standalone SDL frontend or as a libretro core (e.g. with RetroArch).
- CPU: M-cycle accurate
- PPU: T-cycle accurate (implements Pixel FIFO)
- APU (audio)
- Cartridges: NoMBC, MBC1, MBC2, MBC3, MBC5, HUC1, HUC3
- Real Time Clock (RTC) emulation
- Memory buses (EXT, CPU, OAM, VRAM) and MMU (for accurately handle read/write conflicts)
- Timers
- Interrupts
- DMA
- JoyPad
- STOP instruction
- Serial Transfer (bitwise, as happens with the Serial Link)
- HDMA
- Speed Switch and Double Speed Mode
- VRAM/WRAM bank switch
- DMG compatibility mode (with proper palette selection)
- PPU: CGB only features (CGB palettes, BG attributes, VRAM banks, ...)
- CLI debugger (in GDB style): supports disassemble, breakpoints, watchpoints, step by step execution, rewind, memory viewer, interrupts viewer, IO viewer
- Serial Link (output to console)
- Save/Load
- Save/Load state
- Fast-forward
- Configurable palette
- Screenshots
- Graphical menu (SDL)
You can find the latest executables for both Windows and Linux in the Releases Page.
Alternatively, you can build the project by yourself as explained below.
Clone the repository and its submodules.
git clone https://github.com/Docheinstein/docboy.git --recurse-submodules
DocBoy can be compiled as a static library which can be used by a frontend.
These are the CMake options for the available frontends.
BUILD_SDL_FRONTEND(default)BUILD_LIBRETRO_COREBUILD_LIBRETRO_CORE_ANDROIDBUILD_NOGUI_FRONTEND
SDL
mkdir build
cd build
cmake ..
make -j 8
Additional dependencies:
- An audio framework: for Linux you can install alsa-lib
Libretro Core
mkdir build
cd build
cmake .. -DBUILD_LIBRETRO_CORE=ON
make -j 8
Android
- Install NDK.
- Enable the CMake option
BUILD_LIBRETRO_CORE_ANDROID. - Set the CMake option
NDK_PATHto your NDK path (the folder should contain thendk-pathexecutable).
That is:
mkdir build
cd build
cmake .. -DBUILD_LIBRETRO_CORE_ANDROID=ON -DNDK_PATH=/opt/AndroidSdk/ndk/25.2.9519653/build
make
Note: use just make instead of make -j; the latter does not work with NDK build.
These are all the supported CMake options.
| CMake option | Description | Default Value |
|---|---|---|
| BUILD_TESTS | Build tests | OFF |
| BUILD_DEVTOOLS | Build devtools | OFF |
| BUILD_NOGUI_FRONTEND | Build NoGUI frontend | OFF |
| BUILD_SDL_FRONTEND | Build SDL frontend | ON |
| BUILD_LIBRETRO_CORE | Build libretro core | OFF |
| BUILD_LIBRETRO_CORE_ANDROID | Build libretro core for Android | OFF |
| NDK_PATH | NDK path for Android build | |
| ENABLE_DEBUGGER | Enable debugger | OFF |
| ENABLE_BOOTROM | Enable boot rom | OFF |
| ENABLE_AUDIO | Enable audio | ON |
| ENABLE_CGB | Enable GameBoy Color | ON |
| ENABLE_TWO_PLAYERS_MODE | Enable two players mode (serial link) | ON |
| ENABLE_ASSERTS | Enable asserts | OFF |
| ENABLE_STATE_DEBUG_SYMBOLS | Add source code symbols to state files | OFF |
| ENABLE_DIRECT_LCD_RENDERING | Enable rendering directly to LCD framebuffer | OFF |
usage: [rom] [--config CONFIG] [--serial] [--scaling SCALING] [--cartridge-info]
[--debugger] [--help]
positional arguments:
rom ROM
options:
-c, --config CONFIG Read configuration file
-s, --serial Display serial console
-z, --scaling SCALING Scaling factor
-i, --cartridge-info Dump cartridge info and quit
-d, --debugger Attach debugger
-h, --help Display this help message and quit
Controls
These are the default controls.
All the joypad keys can be remapped through the Control Options menu.
| Button | Action |
|---|---|
| F1 | Save State |
| F2 | Load State |
| F11 | Dump framebuffer |
| F12 | Screenshot |
| F | Show / Hide FPS |
| Q | Decrease speed |
| W | Increase speed |
| D | Attach / Detach debugger |
| Enter | START |
| Tab | SELECT |
| Z | A |
| X | B |
| Up | UP |
| Right | RIGHT |
| Down | DOWN |
| Left | LEFT |
With RetroArch (supported by almost every existing platform, including Android and iOS), you can Load Core the libretro core compiled with the BUILD_LIBRETRO_CORE or BUILD_LIBRETRO_CORE_ANDROID.
If you're on a desktop environment, you can also load the core from command line:
retroarch -L build/docboy_libretro.so <rom>
The road to perfect emulation is impossible still far away, nevertheless DocBoy aims to be a fairly accurate emulator, eventually at the cost of sacrificing a bit of performance.
Practically all the features are covered by the tests under the tests/roms folder, most of which come either from docboy-test-suite or other public test suites.
DocBoy is part of the GBEmulatorShootout comparison as well, which contains the tests results of the most popular emulators.
To run the tests locally, build with the CMake option BUILD_TESTS enabled:
mkdir build
cd build
cmake .. --DBUILD_TESTS=ON
make -j 8
Then run the docboy-tests executable (run with --help or see Catch2 for allowed options).
DocBoy offers a CLI debugger (in GDB style) that's really useful to see what's going on under the hood.
To build with the debugger support, enable the CMake ENABLE_DEBUGGER option.
mkdir build
cd build
cmake .. -DENABLE_DEBUGGER=ON
make -j 8
Use the -d option to run with the debugger already attached from the beginning, or press the key D to attach/detach the debugger at any time.
Commands
With help you can list the commands:
h
b <addr> : Set breakpoint at <addr>
w[/r|a] <start>,<end> [<cond>] : Set watchpoint from <start> to <end>
w[/r|a] <addr> [<cond>] : Set watchpoint at <addr>
del <num> : Delete breakpoint or watchpoint <num>
ad <past> <next> : Automatically disassemble past <past> and next <next> instructions
ad <num> : Automatically disassemble next <num> instructions (default = 10)
x[x][/<length><format>] [<bank>:]<addr> : Display memory at <addr> (x: raw) (<format>: x, h[<cols>], b, d, i)
/b <bytes> : Search for <bytes>
/i <bytes> : Search for instructions matching <bytes>
display[x][/<length><format>] [<bank>:]<addr> : Automatically display memory at <addr> (x: raw) (<format>: x, h[<cols>], b, d, i)
undisplay : Undisplay expressions set with display
key <press|release> <key> : Send 'press' or 'release' event for <key> (<key>: a, b, start, select, up, down, left, right)
t [<count>] : Continue running for <count> clock ticks (default = 1)
. [<count>] : Continue running for <count> PPU dots (default = 1)
s [<count>] : Continue running for <count> instructions (default = 1)
si [<count>] : Continue running for <count> micro-operations (default = 1)
n [<count>] : Continue running for <count> instructions at the same stack level (default = 1)
ni [<count>] : Continue running for <count> micro-operations at the same stack level (default = 1)
f [<count>] : Continue running for <count> frames (default = 1)
fb [<count>] : Step back by <count> frames (default = 1, max = 600)
l [<count>] : Continue running for <count> lines (default = 1)
c [<address>] : Continue (optionally stop at <address>)
trace [<flag1>] [<flagN>] : Set the trace modes (output on stderr)
d : Dump the disassemble (output on stderr)
symbols : Show the symbols (if .sym is available)
r : Reset the emulator to its initial state
save [<path>] : Save state to <path>
load [<path>] : Load state from <path>
h : Display help
q : Quit
Here's the debugger!
Contributions are welcome!
If you encounter a bug, a failing test ROM, or would like to propose a new feature, please open an issue and/or submit a PR.