Go to file
Lior Halphon b7f03dea8d Add CGB-A support 2022-01-05 21:55:46 +02:00
.github Give APU tests more time 2021-10-07 18:30:09 +03:00
BootROMs CGB-0 support 2021-11-04 00:35:44 +02:00
Cocoa Add CGB-A support 2022-01-05 21:55:46 +02:00
Core Add CGB-A support 2022-01-05 21:55:46 +02:00
FreeDesktop Fix the desktop categories. 2021-04-23 20:43:34 +02:00
HexFiend Improved Dark Mode support, improved Hex Fiend's general system-native appearance 2020-06-10 01:10:11 +03:00
JoyKit Switch Pro Controller motion controls 2021-11-22 23:29:10 +02:00
Misc Register name and info update 2021-11-06 13:34:34 +02:00
OpenDialog Remove Cocoa spam from the SDL port 2021-09-09 00:11:49 +03:00
QuickLook Drop BOOLs 2021-10-23 13:36:58 +03:00
SDL CGB-0 support 2021-11-04 00:35:44 +02:00
Shaders Fixed dark colors on Metal without frame blending 2020-12-12 16:02:46 +02:00
Tester Fix sanity 2021-10-09 23:12:49 +03:00
Windows New console readline-like interface for the SDL port 2021-09-09 00:13:09 +03:00
libretro CGB-0 support 2021-11-04 00:35:44 +02:00
.gitattributes Add .gitattributes line ending settings 2020-12-19 00:58:19 -05:00
.gitignore Initial public commit 2016-04-01 21:27:01 +03:00
BESS.md Replace the term sprite with object for consistency 2021-12-17 21:16:23 +02:00
CHANGES.md Updated documents to refer to the new website 2017-02-05 21:50:46 +02:00
CONTRIBUTING.md Create CONTRIBUTING.md 2020-09-29 20:43:47 +03:00
LICENSE Update version and copyright date 2021-02-27 19:08:32 +02:00
Makefile Enable LTO in Windows builds, fix missing MGB boot in SDL 2021-12-31 00:40:34 +02:00
README.md Update readme 2021-02-27 15:37:40 +02:00
build-faq.md Update RGBDS links in README and build-faq 2020-10-13 18:19:29 -04:00
version.mk Update version to 0.14.7 2021-10-30 16:10:26 +03:00



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 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
  • Extremely high accuracy
  • Emulates PCM_12 and PCM_34 registers
  • T-cycle accurate emulation of LCD timing effects, supporting the Demotronic trick, Prehistorik Man, GBVideoPlayer and other tech demos
  • Real time clock emulation
  • Retina/High DPI display support, allowing a wider range of scaling factors without artifacts
  • Optional frame blending (Requires OpenGL 3.2 or later)
  • Several scaling algorithms (Including exclusive algorithms like OmniScale and Anti-aliased Scale2x; Requires OpenGL 3.2 or later or Metal)

Features currently supported only with the Cocoa version:

  • Native Cocoa interface, with support for all system-wide features, such as drag-and-drop and smart titlebars
  • Game Boy Camera support

Read more.


SameBoy passes all of blargg's test ROMs, all of mooneye-gb's tests (Some tests require the original boot ROMs), and all of Wilbert Pol's tests. SameBoy should work with most games and demos, please report any broken ROM. The latest results for SameBoy's automatic tester are available here.


SameBoy is an open-source project licensed under the MIT license, 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.


SameBoy requires the following tools and libraries to build:

  • clang (Recommended; required for macOS) or GCC
  • make
  • macOS Cocoa port: macOS SDK and Xcode (For command line tools and ibtool)
  • SDL port: libsdl2
  • rgbds, for boot ROM compilation

On Windows, SameBoy also requires:

  • Visual Studio (For headers, etc.)
  • GnuWin
  • Running vcvars32 before running make. Make sure all required tools and libraries are in %PATH% and %lib%, 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), libretro, bootroms and 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. 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.