Video summary

Gameboy Emulator Development - Part 01

Main summary

Key takeaways

Technology

Summary of the video (Game Boy emulator dev, Part 01)

Goal of the series

  • Build a cycle-accurate Game Boy emulator (“as cycle accurate as I can”) to deepen understanding of:
    • Low-level programming
    • Computer systems
    • Computer architecture
  • The motivation is educational rather than commercial:
    • Acknowledges that other emulators already exist
    • Frames this project as a learning exercise, not a product replacement

Demo / current status of the emulator

  • The creator shows the emulator running The Legend of Zelda (the ROM appears to be in German).
  • The UI includes debug screens:
    • Left: debug output (details not finalized)
    • Right: active sprites and their positions
    • Bottom: palette / available sprites
  • Zelda is highlighted as a “good demo” because it exercises many behaviors that simpler games may skip—e.g. compared to Tetris, which can ignore advanced cases like:
    • Sprite sizes
    • Scrolling complexities
  • In Part 01, most emulator components are still stubs, notably that CPU instruction execution isn’t fully implemented.

Tech stack / setup guide (Ubuntu 20.x focus, with notes for Windows)

  • Installs SDL2 development libraries (libsdl2-dev) for graphics.
  • Installs build tools and related dependencies:
    • build-essential (compiler toolchain, etc.)
    • cmake
    • libSDL2_ttf-dev (SDL2 TrueType fonts)
    • check (unit testing framework; later used for libcheck)
    • git (uses git clone)
  • Editor install (Linux):
    • Installs Visual Studio Code via the .deb package.

Project structure and portability

  • Uses CMake to support building on Windows/macOS/Linux without hunting platform-specific libraries.
  • Repository includes:
    • Test ROMs in a roms/ folder
      • The creator notes they can’t widely host copyrighted ROMs, but included test assets are available for users to download themselves.
    • Documentation links:
      • Full Game Boy technical reference (PDF)
      • A cycle accuracy resource by Antonio Nino Diaz
      • Pan Docs (Game Boy reference hub)
      • CPU instruction set/opcode docs for the LR35902
  • A Discord server is mentioned, including a potential emulator-dev channel for questions.

Emulation architecture described

Core design choice

  • Avoids global variables by using context structs (“contexts” per component), allowing multiple emulator instances in theory.
  • For this series, it remains one instance for simplicity.

Key components mentioned

  • Emulator context (emu)
    • Stores state such as pause, running, and a ticks counter
    • Exposes emu_run
  • Main emulator loop
    1. Load cartridge
    2. Initialize SDL/TTF (for eventual UI rendering)
    3. Initialize CPU
    4. Run loop:
      • If paused: sleep (10 ms)
      • Else: perform one CPU step (cpu_step)
      • Increment ticks
      • Exit if CPU stepping fails

Subsystems (mostly stubbed in Part 01)

  • cartridge module
    • Real loading/validation implemented
  • cpu module
    • cpu_step currently prints “not implemented” and returns failure/false
  • ppu module (pixel processing unit)
    • Not implemented yet
  • timer module
    • Not implemented yet
  • Bus abstraction
    • 8-bit data bus + 16-bit address bus
    • Routes reads/writes to mapped components (e.g., cartridge for certain address ranges)

Cartridge format + implementation details (real functionality)

Header fields parsed

  • Uses Game Boy cartridge header fields from Pan Docs / the technical reference:
    • Header starts at 0x100
    • Contains:
      • Entry point
      • Nintendo logo
      • Game title
      • Metadata including:
        • Licensee codes (new/old)
        • Cartridge type (ROM-only, MBC variants)
        • ROM size
        • RAM size
        • Destination code
        • Checksum, etc.

CGB-related fields

  • Some Game Boy Color (CGB) header bytes aren’t relevant for the project’s monochrome Game Boy focus, so the creator plans to ignore them for now.

Checksum validation

  • Runs the standard cartridge header checksum algorithm.
  • If the checksum matches the expected value (described as comparing to 0xFF), the ROM is considered valid.

Loading process

  • Reads the full ROM file into memory:
    • Uses fopen, fseek/ftell, malloc, fread
  • Parses header data using lookup tables:
    • Vendor/publisher licensee names
    • ROM type decoding
  • Prints parsed results:
    • Title
    • ROM type (hex + string)
    • ROM size
    • RAM size
    • Licensee
    • ROM version
    • Checksum pass/fail

Cartridge context includes

  • Filename
  • ROM size
  • Loaded ROM bytes
  • Parsed header info

Build + test instructions (implemented in this part)

Build steps

  • Create a build/ directory
  • Run:
    • cmake ..
    • make

Outputs

  • Shared library: libemu
  • Executables:
    • gbemu
    • check-gb

Testing

  • Uses unit tests via check / libcheck.
  • Example test:
    • test_nothing expects cpu_step to return false because CPU stepping is not implemented yet.
  • Reported test result:
    • 100% success

Emulator execution examples (what the demo shows)

  • Running gbemu on various ROMs prints cartridge metadata, then stops because the CPU isn’t implemented yet.
  • Examples mentioned:
    • “Dmg-acid 2” (ROM-only, checksum passed)
    • Tetris (ROM-only)
    • Super Mario Land (MBC1 variants; described as type 1/nbc one in subtitles)
    • Empire Strikes Back (larger MBC1)
    • Adventure Island (MBC1 + no RAM)
    • Zelda (MBC1 + RAM + battery; larger ROM size; includes RAM size)

Main speakers / sources

Speaker

  • The YouTube creator/host (“low level dev” / channel host; no specific name given in subtitles)

Referenced technical sources

  • Pan Docs (Game Boy reference repository)
  • Cycle accuracy guide by Antonio Nino Diaz
  • Game Boy Complete Technical Reference PDF (linked/mentioned in the project docs)
  • LR35902 instruction set / opcode documentation (referenced for CPU emulation)

Original video