https://github.com/sysprog21/gameboy-emu
An efficient and portable Game Boy emulator
https://github.com/sysprog21/gameboy-emu
gameboy gameboy-emulator gbz80 sdl2
Last synced: about 1 month ago
JSON representation
An efficient and portable Game Boy emulator
- Host: GitHub
- URL: https://github.com/sysprog21/gameboy-emu
- Owner: sysprog21
- License: mit
- Created: 2020-11-23T07:16:23.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-06-26T15:31:18.000Z (12 months ago)
- Last Synced: 2025-05-08T23:54:00.040Z (about 1 month ago)
- Topics: gameboy, gameboy-emulator, gbz80, sdl2
- Language: C
- Homepage:
- Size: 79.1 KB
- Stars: 36
- Watchers: 5
- Forks: 6
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# gameboy-emu
`gameboy-emu` aims to be an efficient and portable Game Boy emulator.
Only the original Game Boy (DMG) is supported at this time.
The performance is the major consideration, and please look for an
alternative emulator if accuracy is crucial to you.
## Build and Verify
`gameboy-emu` relies on some 3rd party packages to be fully usable and to
provide you full access to all of its features. You need to have a working
[SDL2 library](https://www.libsdl.org/) on your target system.
* macOS: `brew install sdl2`
* Ubuntu Linux / Debian: `sudo apt install libsdl2-dev`
Build the emulator.
```shell
make
```
`build/emu` is the built executable file, and you can use it to load Game Boy
ROM files.
`build/bench` profiles the emulation of GBZ80 CPU.
Since the GNU/Linux build of `bench` uses `perf_event_open`, make sure to have
the permission to access the performance counters: either run the program as
superuser (discouraged) or set the value of `perf_event_paranoid` appropriately,
for example:
```shell
echo 1 | sudo tee /proc/sys/kernel/perf_event_paranoid
```
Optionally make it permanent with:
```shell
echo 'kernel.perf_event_paranoid=1' | sudo tee /etc/sysctl.d/local.conf
```
`build/bench` would print the rough number of CPU clock cycles spent in executing
the code during Game Boy emulation with [Blargg's test ROMs](https://github.com/retrio/gb-test-roms).
## Key Controls
| Action | Keyboard | Joypad |
|-------------------|------------|--------|
| A | z | A |
| B | x | B |
| Start | Return | START |
| Select | Backspace | BACK |
| D-Pad | Arrow Keys | DPAD |
| Normal Speed | 1 | |
| Turbo x2 (Hold) | Space | |
| Turbo X2 (Toggle) | 2 | |
| Turbo X3 (Toggle) | 3 | |
| Turbo X4 (Toggle) | 4 | |
| Reset | r | |
| Change Palette | p | |
| Reset Palette | Shift + p | |
| Fullscreen | F11 / f | |
| Frameskip (Toggle)| o | |
| Interlace (Toggle)| i | |
Frameskip and Interlaced modes are both off by default. The Frameskip toggles
between 60 FPS and 30 FPS.
## Reference
* [Gameboy CPU (LR35902) instruction set](https://pastraiser.com/cpu/gameboy/gameboy_opcodes.html)
* [Blargg's Gameboy hardware test ROMs](https://github.com/retrio/gb-test-roms)
## License
`gameboy-emu` is licensed under the MIT License.