Crab is a Game Boy, Game Boy Color, and Game Boy Advance emulator written in Crystal. Game Boy and Game Boy Color emulation are very accurate, while Game Boy Advance is considered playable in many games.

The Game Boy and Game Boy Color emulator come from my CryBoy project, which has been ported into this codebase to reduce common logic and bugs between the two. The one downside here is the longer build time thanks to Crystal's slow compilation in release mode.

The Game Boy and Game Boy Color work would not be possible without the Pan Docs, izik's opcode table, the gbz80 opcode reference, The Cycle-Accurate Game Boy Docs, or gekkio's Game Boy: Complete Technical Reference. The Game Boy Advance work would not be possible without GBATEK, Tonc, mGBA, or the wonderful emudev community.

Building

SDL2 is the only library you should need to install. It is available on every major package manager. Of course, the assumption is also that you have the Crystal compiler installed.

After cloning the repository, all you'll need to do is run shards build --release to build the emulator in release mode. This will place the binary at bin/crab.

Usage

Running the emulator simply consists of bin/crab /path/to/bios /path/to/rom.

At the moment, the BIOS is required for GBA games, while the GBC BIOS can be omitted for GB and GBC games. If you omit the GBC BIOS for a GB game, it will select a default 4-color palette that will not be the one typically set by the GBC BIOS.

I may ship the emulator with an open-source replacement GBA BIOS at some point in the future. If you cannot dump the official BIOS from your own console, you can pick up Normatt's replacement BIOS or the one created by DenSinH and fleroviux. Both of these BIOSes should be compatible in most cases, although the official BIOS will always be the most accurate.

Keybindings

The current keybindings are tuned for my personal preferences. If the following layout diagram doesn't work for you, the "a" and "b" keys are also bound to their appropriate keys, as are the arrow keys. Controllers are also supported.

Pixel-Accurate GB / GBC Rendering

To enable the experimental FIFO renderer (as opposed to the scanline renderer), you can run the emulator with the --fifo flag. The current FIFO implementation should work identically to the scanline renderer with the exception that it does not render sprites on column 0 of the LCD. However, it will play games like Prehistorik Man more accurately than the scanline renderer would since that game relies on a cycle-accurate PPU implementation.

Features and Remaining Work

Features

• GB / GBC
  • Accurate sound emulation
  • GLSL shaders for color reproduction
  • Controller support
  • Passing blargg's CPU tests
  • Passing blargg's instruction timing tests
  • Passing blargg's memory timing tests
  • Passing blargg's Game Boy Color sound tests
  • Passing mooneye-gb timer tests
  • PPU draws background, window, and sprites
  • PPU offers both scanline and FIFO rendering modes (behind a runtime flag)
  • Save files work as intended, and are compatible with other emulators like BGB
  • MBC1 cartridges are supported (except for multicarts)
  • MBC2 cartridges are fully supported
  • MBC3 cartridges are supported (except timers)
  • MBC5 cartridges are supported
  • Game Boy Color support, including HDMA, double-speed mode, and palettes
• GBA
  • Accurate sound emulation (both Direct Sound and PSGs)
  • GLSL shaders for color reproduction
  • Controller support
  • PPU features
    • Modes 0-5 are mostly implemented
    • Affine backgrounds and sprites
    • Alpha blending
    • Windowing
  • CPU core
    • Passing armwrestler
    • Passing FuzzARM
    • Passing gba-suite
  • Storage
    • Flash and SRAM implemented
  • Timers run effeciently on the scheduler

Remaining Work

• GB / GBC
  • Picture processing
    • Pixel FIFO
      • I've made lots of progress into the FIFO renderer. There are still a couple of issues that I have yet to resolve, though. The main one that seems to be specific to the pixel FIFO renderer is that I don't render sprites on column 0 of the LCD, although I still do render the rest of the sprite in its correct position even if the sprite's x position is less than 8
  • Misc
    • MBCs
      • MBC 5 rumble
      • RTC (decide if I want it to stick with real time or CPU time, or make it configurable)
      • Fixing an issue when ROMs misreport their size
    • Other hardware bugs tested in blargg's test suite
• GBA
  • PPU
    • Mosaic
    • Blending code needs cleanup
  • Storage
    • EEPROM
    • Game database to support odd cases like Classic NES and ROMs that misreport things like RTC
  • Timing
    • Cycle counting
    • DMA timing
    • Prefetch
    • Etc, etc, etc.

Special Thanks

A special thanks goes out to those in the emudev community who are always helpful, both with insightful feedback and targeted test ROMs.

• https://github.com/ladystarbreeze
• https://github.com/DenSinH
• https://github.com/fleroviux
• https://github.com/destoer

Contributing

1. Fork it (https://github.com/mattrberry/crab/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Matthew Berry - creator and maintainer