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 Apotris

Playing Pokemon Emerald with debugger

TLoZ: Oracle of Ages with running debugger

Status

The AGB (GameBoy Advance) emulator is in a good and usable state. Automated testing of most commercial games shows that most of them are playable, and work without any major glitches. The core is well optimized and ready to be used.

The CGB/DMG (GameBoy [Color]) core is fairly accurate, but still has some bugs left to be worked out. Many games run well.

The NDS core is still very early and unable to boot anything at this time.

Features

General

• Highly configurable, including input (controller support!)
• Savegame support in common .sav format (Basic RTC support)
• Support for creating and loading save states with "undo last load" function
• Fast forwarding (toggle and hold), live rewinding support
• 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 and games
• Replay support for playback of previous inputs
• Able to run in the browser!

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 and threaded PPU
• Remote debugger support (GDB server)
• Support for playing ELF files
• Waitloop detection

System emulation

• DMG/CGB

  • Most commercial games running glitch-free
  • Full SM83 CPU
    • 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

• AGB

  • Most commercial games running glitch-free
  • Full ARM7DTMI CPU
  • Open bus behavior
  • PPU
    • Passing precise visual tests
    • Everything else
  • APU
  • DMAs
  • Timers
  • Cartridge save types
  • RTC

• NTR

  • ARM7 and ARM9 CPUs
    • ARM7
    • ARM9
    • ARM9 CP15
  • FIFO
  • PPU
    • Tile PPU
    • 3D Engine
  • Timers
  • DMA
  • Cartridge support
  • Memory control
  • Many other things

Planned Features

• Save export on Web/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

GG/GGC

• All Blargg tests (oam_bug untested)
• Mooneye
  • acceptance: 41/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: 130/130
  • Timing: 1395/2020
  • Timer count-up: Freezes...
  • Timer IRQ: 90/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/+{IW,EW}RAM" 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: 9/9
  • 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

NDS

• ARMWrestler
• rockwrestler
  • ARMv4
  • ARMv5
  • IPC
  • DS Math
  • Memory

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
• michelhe, for their emulator
• fleroviux, for NBA and it's MP2K implementation