SameBoy is an open source Game Boy (DMG) and Game Boy Color (CGB) emulator, written in portable C.
SameBoy is an open-source emulator for the Game Boy (DMG) and Game Boy Color (CGB), written in portable C. It provides high-accuracy emulation of both systems, supporting features such as battery save, save states, and advanced debugging tools.
Key Features:
High Accuracy: Passes all major test ROMs, including blargg’s and mooneye-gb tests.
Multi-Platform Support: Runs on macOS (Cocoa frontend), Linux/FreeBSD (SDL frontend), and Windows.
Advanced Debugging: Includes a text-based debugger with disassembly, breakpoints, watchpoints, and an expression evaluator.
High-Quality Audio: Emulates PCM_12 and PCM_34 registers for accurate sound reproduction.
Custom Palettes: Supports manual palette selection with additional palettes for CGB games.
Audience & Benefit:
Ideal for retro gaming enthusiasts, game developers, and educators seeking precise emulation of Game Boy classics. SameBoy also serves as a powerful development tool for testing and debugging through its advanced debugging capabilities.
SameBoy can be installed via winget on compatible systems.
README
SameBoy
SameBoy is an open source Game Boy (DMG) and Game Boy Color (CGB) emulator, written in portable C. It has a native Cocoa frontend for macOS, an SDL frontend for other operating systems, and a libretro core. It also includes a text-based debugger with an expression evaluator. Visit the website.
Features
Features common to both Cocoa and SDL versions:
Supports Game Boy (DMG) and Game Boy Color (CGB) emulation
Lets you choose the model you want to emulate regardless of ROM
High quality 96KHz audio
Battery save support
Save states
Includes open source DMG and CGB boot ROMs:
Complete support for (and documentation of) all game-specific palettes in the CGB boot ROM, for accurate emulation of Game Boy games on a Game Boy Color
Supports manual palette selection with key combinations, with 4 additional new palettes (A + B + direction)
Supports palette selection in a CGB game, forcing it to run in 'paletted' DMG mode, if ROM allows doing so.
Support for games with a non-Nintendo logo in the header
No long animation in the DMG boot
Advanced text-based debugger with an expression evaluator, disassembler, conditional breakpoints, conditional watchpoints, backtracing and other features
SameBoy passes all of blargg's test ROMs, all of mooneye-gb's tests (Some tests require the original boot ROMs), and all of . SameBoy should work with most games and demos, please any broken ROM. The latest results for SameBoy's automatic tester are available .
SameBoy is an open-source project licensed under the Expat license (with an additional exception for the iOS folder), and you're welcome to contribute by creating issues, implementing new features, improving emulation accuracy and fixing existing open issues. You can read the contribution guidelines to make sure your contributions are as effective as possible.
Compilation
SameBoy requires the following tools and libraries to build:
clang (Recommended; required for macOS) or GCC
make
macOS Cocoa frontend: macOS SDK and Xcode (For command line tools and ibtool)
cppp, for cleaning up headers when compiling SameBoy as a library
On Windows, SameBoy also requires:
Visual Studio (For headers, etc.)
Git Bash or another distribution of basic Unix utilities
Git Bash does not include make, you can get it here.
Running vcvars64.bat or vcvarsx86_amd64.bat before running make. Make sure all required tools, libraries, and headers are in %PATH%, %lib%, and %include%`, respectively. (see Build FAQ for more details on Windows compilation)
To compile, simply run make. The targets are:
cocoa (Default for macOS)
sdl (Default for everything else)
lib (Creates libsameboy.o and libsameboy.a for statically linking SameBoy, as well as a headers directory with corresponding headers; currently not supported on Windows due to linker limitations)
ios (Plain iOS .app bundle), ios-ipa (iOS IPA archive for side-loading), ios-deb (iOS deb package for jailbroken devices)
libretro
bootroms
tester
You may also specify CONF=debug (default), CONF=release, CONF=native_release or CONF=fat_release to control optimization, symbols and multi-architectures. native_release is faster than release, but is optimized to the host's CPU and therefore is not portable. fat_release is exclusive to macOS and builds x86-64 and ARM64 fat binaries; this requires using a recent enough clang and macOS SDK using xcode-select, or setting them explicitly with CC= and SYSROOT=, respectively. All other configurations will build to your host architecture, except for the iOS targets. You may set BOOTROMS_DIR=... to a directory containing precompiled boot ROM files, otherwise the build system will compile and use SameBoy's own boot ROMs.
The SDL port will look for resource files with a path relative to executable and inside the directory specified by the DATA_DIR variable. If you are packaging SameBoy, you may wish to override this by setting the DATA_DIR variable during compilation to the target path of the directory containing all files (apart from the executable, that's not necessary) from the build/bin/SDL directory in the source tree. Make sure the variable ends with a / character. On FreeDesktop environments, DATA_DIR will default to /usr/local/share/sameboy/. PREFIX and DESTDIR follow their standard usage and default to an empty string an /usr/local, respectively
Linux, BSD, and other FreeDesktop users can run sudo make install to install SameBoy as both a GUI app and a command line tool.
SameBoy is compiled and tested on macOS, Ubuntu and 64-bit Windows 10.