Troubleshooting and FAQ
Building
CMake cannot find SDL2
The SDL2 development files are missing. On Debian or Ubuntu, install them and configure again:
sudo apt install libsdl2-devOn Windows, install SDL2 with vcpkg and pass the vcpkg toolchain file to CMake, as shown in Install.
The compiler rejects the code
gameboy is written in C++20. Use a recent GCC, Clang or Visual Studio 2022.
Running
gameboy prints its usage text and exits
No ROM file was named, or an option was misspelt. An error: unknown option line above the usage text names a bad option.
error: unsupported cartridge type
The ROM uses a cartridge chip gameboy does not emulate. Only ROM-only, MBC1 and MBC3 (banking only) are supported. See Which ROMs run.
error: ROM too small to have a header
The file is not a Game Boy ROM, or the download is incomplete.
The window closes with CPU stopped
The program ran a STOP instruction or an illegal opcode, and the emulator quit. The ROM may be damaged or may need hardware gameboy does not emulate.
My progress is gone after restarting
gameboy does not write battery saves or save states. This is a known limit of version 1.
A game that uses the clock behaves oddly
The MBC3 real-time clock is not emulated. Games read a fixed value from it.
The picture tears in one game
A few games change graphics settings in the middle of a scan line. gameboy draws each line in one go, so those effects can shear. Most games are not affected.
There is no sound
Check that you did not pass --mute and that Tab or --turbo is not active: turbo drops sound. If the terminal shows warning: no audio device, your system has no usable audio output.
The game runs too fast
You started with --turbo, or Tab is held down. Without turbo, gameboy runs at the real console's speed.
Questions
Where do I get ROMs?
None are bundled. tests/roms/fetch_roms.sh downloads free test ROMs. For games, use homebrew released by its author, or dump cartridges you own. Do not download commercial games you do not own.
Does it run Game Boy Color games?
No. Game Boy Color mode is out of scope.
Can I use a gamepad or remap the keys?
No. Input is the fixed keyboard layout in the reference.
Can two emulators link up?
No. The link cable is not emulated.
Where do I report a problem?
Open an issue on the gameboy issues page.