Project 5: Game Boy Emulator

An emulator for the original Nintendo Game Boy. It will read ROM files, execute CPU instructions, and (eventually) render graphics.

Quick Reference

Attribute Value
Primary Language Zig
Alternative Languages C, C++, Rust
Difficulty Level 3: Advanced
Time Estimate 1 month+
Knowledge Area Emulation / Low-Level Programming
Tooling A CPU emulator
Prerequisites Project 1, 2, and 4. Strong understanding of computer architecture.

What You Will Build

An emulator for the original Nintendo Game Boy. It will read ROM files, execute CPU instructions, and (eventually) render graphics.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Implementing the Z80-like CPU → maps to a giant switch statement, bitwise operations, and integer overflow handling (@addWithOverflow)
  • Memory-Mapped I/O (MMIO) → maps to managing reads/writes to specific memory addresses that control hardware like the PPU (Pixel Processing Unit)
  • Decoding opcodes → maps to complex bit masking and shifting
  • Managing the CPU state machine → maps to structs, unions, and careful state management

Key Concepts

  • CPU Emulation: “Game Boy Emulation in Rust” (blog series) - provides the concepts, you apply them in Zig.
  • Bitwise Operations: Zig documentation on bitwise operators (|, &, ^, <<, >>).
  • Integer Handling: Zig’s arbitrary-bit-width integers (e.g., u1, i7) and overflow builtins.

Real-World Outcome

$ zig run main.zig -- roms/tetris.gb
# A window opens showing the Tetris title screen

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: LEARN_ZIG_DEEP_DIVE.md
  • Pan Docs (Game Boy technical reference)