SameBoy | Accurate GB/GBC emulator |
| download: https://git.y1.nz/archives/sameboy.tar.gz | |
| README | Files | Log | Refs | LICENSE |
README.md
1 # SameBoy
2
3 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](https://sameboy.github.io/).
4
5 ## Features
6 Features common to both Cocoa and SDL versions:
7 * Supports Game Boy (DMG) and Game Boy Color (CGB) emulation
8 * Lets you choose the model you want to emulate regardless of ROM
9 * High quality 96KHz audio
10 * Battery save support
11 * Save states
12 * Includes open source DMG and CGB boot ROMs:
13 * 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
14 * Supports manual palette selection with key combinations, with 4 additional new palettes (A + B + direction)
15 * Supports palette selection in a CGB game, forcing it to run in 'paletted' DMG mode, if ROM allows doing so.
16 * Support for games with a non-Nintendo logo in the header
17 * No long animation in the DMG boot
18 * Advanced text-based debugger with an expression evaluator, disassembler, conditional breakpoints, conditional watchpoints, backtracing and other features
19 * Extremely high accuracy
20 * Emulates [PCM_12 and PCM_34 registers](https://github.com/LIJI32/GBVisualizer)
21 * T-cycle accurate emulation of LCD timing effects, supporting the Demotronic trick, Prehistorik Man, [GBVideoPlayer](https://github.com/LIJI32/GBVideoPlayer) and other tech demos
22 * Real time clock emulation
23 * Retina/High DPI display support, allowing a wider range of scaling factors without artifacts
24 * Optional frame blending (Requires OpenGL 3.2 or later)
25 * Several [scaling algorithms](https://sameboy.github.io/scaling/) (Including exclusive algorithms like OmniScale and Anti-aliased Scale2x; Requires OpenGL 3.2 or later or Metal)
26
27 Features currently supported only with the Cocoa version:
28 * Native Cocoa interface, with support for all system-wide features, such as drag-and-drop and smart titlebars
29 * Game Boy Camera support
30
31 [Read more](https://sameboy.github.io/features/).
32
33 ## Compatibility
34 SameBoy passes all of [blargg's test ROMs](http://gbdev.gg8.se/wiki/articles/Test_ROMs#Blargg.27s_tests), all of [mooneye-gb's](https://github.com/Gekkio/mooneye-gb) tests (Some tests require the original boot ROMs), and all of [Wilbert Pol's tests](https://github.com/wilbertpol/mooneye-gb/tree/master/tests/acceptance). SameBoy should work with most games and demos, please [report](https://github.com/LIJI32/SameBoy/issues/new) any broken ROM. The latest results for SameBoy's automatic tester are available [here](https://sameboy.github.io/automation/).
35
36 ## Contributing
37 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](CONTRIBUTING.md) to make sure your contributions are as effective as possible.
38
39 ## Compilation
40 SameBoy requires the following tools and libraries to build:
41 * clang (Recommended; required for macOS) or GCC
42 * make
43 * macOS Cocoa frontend: macOS SDK and Xcode (For command line tools and ibtool)
44 * SDL frontend: libsdl2
45 * When building for operating systems other than Windows and macOS, libpng is also required
46 * [rgbds](https://github.com/gbdev/rgbds/releases/), for boot ROM compilation
47 * [cppp](https://github.com/LIJI32/cppp), for cleaning up headers when compiling SameBoy as a library
48
49 On Windows, SameBoy also requires:
50 * Visual Studio (For headers, etc.)
51 * [Git Bash](https://git-scm.com/downloads/win) or another distribution of basic Unix utilities
52 * Git Bash does not include make, you can get it [here](https://sourceforge.net/projects/ezwinports/files/make-4.4.1-without-guile-w32-bin.zip/download).
53 * 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](https://github.com/LIJI32/SameBoy/blob/master/build-faq.md) for more details on Windows compilation)
54
55 To compile, simply run `make`. The targets are:
56 * `cocoa` (Default for macOS)
57 * `sdl` (Default for everything else)
58 * `lib` (Creates libsameboy.o and libsameboy.a for statically linking SameBoy, libsameboy.dylib/so/dll for dynamically linking SameBoy, as well as a headers directory with corresponding headers)
59 * Static libraries are currently not supported on Windows due to linker limitations.
60 * `ios` (Plain iOS .app bundle), `ios-ipa` (iOS IPA archive for side-loading), `ios-deb` (iOS deb package for jailbroken devices)
61 * `libretro`
62 * `bootroms`
63 * `tester`
64
65 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.
66
67 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
68
69 Linux, BSD, and other FreeDesktop users can run `sudo make install` to install SameBoy as both a GUI app and a command line tool.
70
71 SameBoy is compiled and tested on macOS, Ubuntu and 64-bit Windows 10.
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.