gameboy-sharp/README.md

gameboy-sharp

A Game Boy (DMG) emulator written in C# (.NET 6). The core is a pure library with no frontend dependency, so the whole machine runs and is verified headless.

Status - wave 1

Working, test-verified core that runs real DMG software:

• CPU LR35902: full opcode set + CB prefix, cycle-accurate M-cycle timing, Z/N/H/C flags, interrupts (VBlank/LCD/Timer/Serial/Joypad), HALT + HALT bug, STOP (minimal), delayed EI, DI, RETI.
• MMU: full memory map, I/O registers, echo RAM, OAM DMA.
• Cartridge: header parse, MBC1 (ROM/RAM banking), MBC3 and MBC5 banking (no RTC yet), plain ROM.
• PPU: per-scanline mode 2/3/0 + VBlank timing, LCDC/STAT/SCX/SCY/LY/LYC/WX/WY/BGP/OBP0/OBP1, background + window (with the window internal line counter) + sprites (8x8 and 8x16, X/OAM priority, 10-per-line limit, BG priority), 160x144 framebuffer, STAT/LYC interrupts.
• Timer: DIV/TIMA/TMA/TAC via the internal 16-bit counter, falling-edge detection and the TIMA overflow reload delay.
• Joypad and serial (serial output is captured, which is how the Blargg tests are scored).
• APU: register-level stub (open-bus read masks, NR52 power). No synthesis yet - wave 2.

Layout

• src/GameBoy.Core - the machine (no frontend dependency).
• src/GameBoy.Cli - headless runner: loads a ROM, runs frames, dumps the framebuffer.
• tests/GameBoy.Core.Tests - the verification gate.

Verification gate

dotnet test runs, headless:

• cpu_instrs (Blargg) - asserts the serial log reports Passed and never Failed.
• instr_timing (Blargg) - same serial assertion.
• dmg-acid2 - decodes the reference PNG and asserts the rendered framebuffer matches it pixel for pixel (0 mismatches out of 23040).
• CPU micro tests (flags, DAA, push/pop, CB swap).

dotnet test -c Release

Running a ROM (headless)

dotnet run --project src/GameBoy.Cli -c Release -- <rom.gb> [options]
  --frames N        run N frames (default 60)
  --serial          run until the serial log says Passed/Failed, then print it
  --png <path>      write the framebuffer as an 8-bit grayscale PNG
  --ascii           print the framebuffer as ASCII art
  --ascii-out <p>   write the ASCII art to a file

Examples:

dotnet run --project src/GameBoy.Cli -c Release -- tests/roms/cpu_instrs.gb --serial
dotnet run --project src/GameBoy.Cli -c Release -- tests/roms/dmg-acid2.gb --frames 200 --png acid2.png

Test ROMs and licenses

Vendored under tests/roms/ purely to run the verification gate:

• cpu_instrs.gb, instr_timing.gb - Blargg's Game Boy hardware test ROMs by Shay Green (blargg), released for free distribution. Fetched from https://github.com/retrio/gb-test-roms
• dmg-acid2.gb and dmg-acid2-ref.png - the DMG variant of the PPU acid test by Matt Currie, MIT licensed. Fetched from https://github.com/mattcurrie/dmg-acid2

These are third-party artifacts kept only for testing; their own licenses apply.

Not covered yet (wave 2+)

APU synthesis (4 channels + mixdown), MBC3 RTC + MBC5 corner cases, battery RAM save (.sav), Game Boy Color, a windowed frontend (Raylib-cs/SDL - needs a display, so it was left out of this headless wave), a debugger (breakpoints, disassembler, tile/OAM viewers) and save states.