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 debugging tool.

Usage

Prerequisites

Install Zig (version 0.14.1) and SDL3. If you are using NixOs you could just use the flake.nix to install dependencies.

git clone https://github.com/otaleghani/zigboy
cd zigboy
nix develop

Build

# 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

# 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: The single most comprehensive hardware reference for the Gameboy.
• Game Boy: Complete Technical Reference: In-depth details on instruction timing and hardware quirks.
• Game Boy CPU Instruction Set: Instruction set of the CPU (LR35902)
• Blargg's 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.