https://github.com/otaleghani/zigboy
A Gameboy (DMG) emulator written in Zig and SDL3. Currently supports ROM-only and MBC1 cartridges.
https://github.com/otaleghani/zigboy
emulator gameboy gameboy-emulator retro-gaming sdl3 system-programming zig
Last synced: 9 months ago
JSON representation
A Gameboy (DMG) emulator written in Zig and SDL3. Currently supports ROM-only and MBC1 cartridges.
- Host: GitHub
- URL: https://github.com/otaleghani/zigboy
- Owner: otaleghani
- Created: 2025-08-27T10:22:43.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-08-27T10:38:30.000Z (10 months ago)
- Last Synced: 2025-08-27T19:54:34.598Z (10 months ago)
- Topics: emulator, gameboy, gameboy-emulator, retro-gaming, sdl3, system-programming, zig
- Language: Zig
- Homepage:
- Size: 615 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Zigboy
Zigboy is a Gameboy (DMG) emulator written in Zig. It uses the SDL3 library for windowing, input, and audio. It currently supports ROM-only and MBC1 cartridges.
### Screenshots
Here is a gallery of the emulator in action, running a few classic titles.
---
#### Super Mario Land
| | | |
| :---: | :---: | :---: |
|  |  |  |
|  |  | |
---
#### Tetris
| | | |
| :---: | :---: | :---: |
|  |  |  |
---
#### The Legend of Zelda: Link's Awakening
| | | |
| :---: | :---: | :---: |
|  |  |  |
|  |  |  |
|  | | |
## Features
- *CPU*: Implements the full SM83 (Gameboy-variant Z80) instruction set.
- *PPU (Picture Processing Unit)*: Renders graphics for many classic titles. Handles background tiles, window rendering, and sprites.
- *APU (Audio Processing Unit)*: A basic implementation of the Gameboy's sound hardware is included but is currently buggy and impacts performance. It can be disabled at build time.
- *Cartridge Support*:
- ROM-only cartridges.
- MBC1 (Memory Bank Controller 1) for games with larger ROMs and RAM.
- *Debugging*: Includes optional flags for printing CPU state and generating logs compatible with the [Gameboy Doctor](https://robertheaton.com/gameboy-doctor/) debugging tool.
## Usage
### Prerequisites
Install [Zig](https://ziglang.org/) (version 0.14.1) and [SDL3](https://libsdl.org/). If you are using NixOs you could just use the `flake.nix` to install dependencies.
``` bash
git clone https://github.com/otaleghani/zigboy
cd zigboy
nix develop
```
### Build
``` bash
# Standard build (APU disabled):
zig build
# Build with the (buggy) APU enabled:
zig build -Denable_apu=true
# Build with CPU debug logging for diagnostics:
zig build -Denable_cpu_debug=true
# Build with Gameboy Doctor compatible logging:
zig build -Denable_cpu_debug_gbd=true
```
### Run
``` bash
# Run the emulator with a path to a Gameboy ROM file:
./zig-out/bin/zigboy path/to/your/rom.gb
```
### Controls
The emulator uses the keyboard for input. The default key mappings are:
| Keyboard Key | Gameboy Button |
| :----------- | :------------- |
| W, A, S, D | D-Pad (Up, Left, Down, Right) |
| Z | A Button |
| X | B Button |
| Enter | Start Button |
| P | Select Button |
| Escape | Quit Emulator |
### Compatibility
The emulator is still in an early stage of development. While the goal is broad compatibility, rigorous testing has been focused on a core set of titles.
**Confirmed Playable:**
* *Tetris*
* *The Legend of Zelda: Link's Awakening*
* *Super Mario Land*
Attempting to run other ROMs, especially those using more complex mappers or hitting obscure hardware edge cases, may result in graphical glitches, freezes, or a panic. There are still many bugs to solve, and stability with a wider range of games is a top priority for future development.
## References
This project would not have been possible without the extensive documentation created by the retro-development community. Key resources used during development include:
- [Pan Docs](https://gbdev.io/pandocs/): The single most comprehensive hardware reference for the Gameboy.
- [Game Boy: Complete Technical Reference](https://gekkio.fi/files/gb-docs/gbctr.pdf): In-depth details on instruction timing and hardware quirks.
- [Game Boy CPU Instruction Set](https://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html): Instruction set of the CPU (LR35902)
- [Blargg's GB Test ROMs](https://github.com/retrio/gb-test-roms): A suite of test ROMs used to verify emulator accuracy.
## Current status
This project is a work-in-progress. While many games are playable, there are known issues:
- APU Bugs: The audio implementation has timing and synchronization problems, leading to incorrect sound output.
- Performance: With the APU enabled, the frame rate drops to 40-50 FPS due to inefficiencies in the current implementation.
- Test ROMs: Some of Blargg's hardware test ROMs still fail, indicating inaccuracies in CPU timing or CPU/PPU synchronization.
## Future Improvements
- Fix APU: Debug and rewrite the APU for accuracy and performance.
- Pass Test ROMs: Work towards passing all of Blargg's test ROMs for higher accuracy.
- More Mappers: Add support for MBC2, MBC3, and MBC5 to increase game compatibility.
- UI/UX: Implement features like save states, controller remapping, and display scaling options.