GameGirl

A Gameboy (Color/Advance) emulator and debugger written in Rust, whose GG/GGC core is a rewrite of gamelin.
NDS support is in the works!

Try it in your browser!

Screenshots

Playing Pokemon Emerald

Playing Pokemon Crystal Clear

Pokemon Pinball with running debugger and memory viewer

TLoZ: Oracle of Ages with some visual debugging tools open

Status

The DMG/CGB emulator is in a good and usable state. Both DMG and CGB emulation is complete and quite accurate, enough to make most commercial games run perfectly.
AGB support is getting there. Some things are still missing; especially the PPU needs a few more features implemented. Most games are playable, but with minor graphical glitches.

Features

General

• Highly configurable, including input
• Savegame support in common .sav format (Basic RTC support)
• Support for creating and loading save states with "undo last load" function
• Fast forwarding hotkeys, both toggle and hold
• Rewinding support with little memory use (~1MB per second of rewinding at 60fps)
• Debugger with:
  • Line-by-line advance
  • PC and write breakpoints
  • Memory, register and stack view
  • Cartridge Info Viewer
  • Visual debugging tools: VRAM and map viewers
• Automated running of a bunch of different tests

GG(C)

• Accurate scheduler-based emulation of the system
• Complete and M-cycle cycle-accurate DMG/CGB implementation, including running DMG games on CGB
• Colour correction for CGB

GGA

• Accurate scheduler-based emulation of the system
• A cached interpreter
• Remote debugger support (GDB server)
• Support for playing ELF files

System emulation

• DMG/CGB

  • Most commercial games running glitch-free
  • Full SM83 CPU
    • Full instruction set implemented and passing tests
    • M-cycle accuracy
    • Highly accurate interrupts (Pinball Fantasy)
  • PPU
    • Passing visual tests
    • OAM bug
    • Variable OAM scan timings
  • Timer
    • Passing blargg tests
    • Passing mooneye tests
  • OAM DMA
  • APU
  • Cartridge mappers
    • MBC1
    • MBC2
    • MBC3
    • MBC5
  • CGB features
    • 2x Speed
    • HDMA
    • Banking
    • PPU: DMG compatibility mode

• AGB

  • Most commercial games running glitch-free
  • Full ARM7DTMI CPU
    • Instruction-level accuracy
    • Accurate interrupts
    • Accurate waitstates
    • Cached interpreter
  • Open bus behavior
  • PPU
    • Passing visual tests
    • Text mode Backgrounds
    • Bitmap mode Backgrounds
    • Objects
    • Priority
    • Blending
    • Affine BGs/objects
    • Windows
    • Window blending
    • Semi-transparent OBJs
  • APU
    • CGB sound channels
    • DMA sound channels
    • All Volume control registers
  • DMAs
    • General transfers
    • Fine register behavior (Not replacing address if invalid, etc)
    • APU FIFO transfers
    • GamePak EEPROM transfers
    • DMA3 Video Capture
  • Timers
    • Scheduled timers
    • Cascading timers
    • APU FIFO ticking
  • Cartridge save types
    • EEPROM
    • SRAM
    • Flash

Planned Features

• Controller support
• Save export on Web/WASM
• Fix savestates/rewinding on WASM

Goals

The main goals of this emulator is to create a nice-to-use emulator with many comfort features that should be able to run well in the browser. Accuracy is also a goal however, with the only exception being details that noticeably hurt performance to implement.

Missing console features

• GG: Some MBC3 controllers have a built-in RTC for keeping track of time; gamegirl implements it, but in a very simple format incompatible with other emulators that has a high chance of not working with most games (it was tested with Pokemon Crystal and successfully kept time after turning the game off overnight - needs more testing). It is the same format used by Gamelin.

Build

cargo build --release
# Release binary now in target/release/gamegirl_bin.

You will probably get an error about missing firmware files for PSX and NDS - if you do not plan on using those cores, simply supply empty files.

Testing

Test ROMs can be run automatically:

# Run GGA test roms
cargo run -p tests --release

# Also run GG test roms
cargo run -p tests --release -- --gg

GG/GGC

• Blargg
  • Sound tests (some wave RAM issues)
  • oam_bug (untested)
  • Everything else
• Mooneye
  • acceptance: 42/70 (Some tests for DMG/MGB/SGB-specific behavior disabled)
  • emulator-only: 27/28 (MBC1M, not supported)
• Acid2
  • dmg-acid2
  • dmg-acid2 in CGB mode
  • cgb-acid2

GGA

• mgba's suite
  • Memory: 1552/1552
  • I/O read: 123/123
  • Timing: 1272/2020
  • Timer count-up: Freezes...
  • Timer IRQ: 65/90
  • Shifter: 140/140
  • Carry: 93/93
  • Multiply long: 52/72 (cosidered complete; carry is still not researched in general)
  • BIOS math: 625/625
  • DMA tests: 1248/1256
    • "0 Imm H/W R+0x10" tests fail (DMA0 with ROM?)
  • Misc. edge case tests: 7/10
  • Video Tests
    • Basic Mode 3
    • Basic Mode 4
    • Degenerate OBJ transforms
    • Layer toggle
    • OAM Update Delay
• AGS Aging Cartridge
  • Memory: 8/9 (Prefetch buffer fails)
  • LCD
  • Timer: 2/3 (Timer Connect fails)
  • DMA
  • COM
  • Key Input
  • Interrupt
• jsmolka's gba-tests
  • arm
  • memory
  • thumb
  • save (All of them)
  • ppu (All of them)
  • nes
  • bios
• destoer's gba_tests
  • cond_invalid
  • hello_world
  • if_ack
  • Unsure of how to interpret results of the rest...
• ladystarbreeze's GBA test collection
• FuzzARM, all 5 precompiled tests
• ARMWrestler

Thanks To

General

• emilk, for creating egui
• The wider Rust community, for its awesome ecosystem
• You, for reading this :)

GG/GGC

• Imran Nazar, for their series of blog posts on GB emulation
• Michael Steil, for The Ultimate Game Boy Talk
• kotcrab, for creating the xgbc emulator I often used to confirm/understand fine behavior
• Amjad50, for their emulator mizu, which I abridged the sound implementation from
• Megan Sullivan, for her list of GB opcodes
• gbdev.io for a list of useful resources and the Pan Docs
• blargg, Gekkio and mattcurie for their test ROMs and retrio for hosting blargg's ROMs

GGA

• endrift, for mGBA, it's test suite and blog, which was my inspiration for doing GGA emulation
• GBATEK, as a technical reference
• mj-hd, for rgba, which I used to properly understand ARM7 emulation details
• jsmolka, for their testing ROMs
• DenSinH, for FuzzARM and GBAC-
• ladystarbreeze, for their testing ROMs
• destoer, for their testing ROMs