README.md

Swift plays Pokemon

Game Boy emulator written in Swift.

Features

• Instruction accurate - while it is not per-cycle accurate, it will run most of the games without any problems.
• Supports following cartridge types (MBC stands for memory bank controller):
  • no MBC - for example: Tetris
  • MBC1 - for example: Legend of Zelda - The Links Awakening and Kirby's Dream Land
  • MBC3 - for example: Pokemon Red
• blargg tests:
  • ✅ cpu_instrs
  • ✅ instr_timing
• Save/load emulator state to file
• Safe from Meltdown and Spectre

Not supported:

• Audio
• stop instruction (0x10 from unprefixed instruction set) - not really used

Source map

• Swift plays Pokemon.xcodeproj - XCode project file. Use this instead of Swift Package Manager (SPM does not support Metal shaders that we use inside GameBoyMac). Although, if your code depends only on GameBoyKit framework, then SPM is ok.

• Sources

  • GameBoyMac - Mac app that runs the emulator. You can use --rom argument to specify ROM (or just give it as a last argument). It uses GameBoyKit framework.

  • GameBoyKit - Main implementation of GameBoy logic. It contains GameBoy class alongside many other useful things like: Cpu, Lcd and Debugger.

  • Code generation - Code generation executable, based on lmmendes/game-boy-opcodes.

• Tests

  • GameBoyKitTests - Unit tests. Most notably it includes basic tests for every CPU instruction.

  • GameBoyKitROMTests - Tiny app that will run ROM based tests, for example Blargg test ROMs. Please note that this an app, not an XCode test target!

• ROMs - directory that holds games/test ROMs.

  • Tests - Blargg - directory to store Blargg test ROMs.

Screenshots

Keys

For the GameBoyMac target (emulator executable) following key map is used:

Action	Key
DPAD-UP	↑
DPAD-DOWN	↓
DPAD-LEFT	←
DPAD-RIGHT	→
B	S
A	A
START	Q
SELECT	W
Save state	R

Tests

Blargg's tests:

Test	Result	Note
cpu_instrs	✅	Essential
instr_timing	✅	Essential
cgb_sound	❌	Audio is not implemented
dmg_sound	❌	Audio is not implemented
interrupt_time	⚠️	Not tested
mem_timing	⚠️	Not tested
halt_bug	❌	No game requires it
oam_bug	❌	Game Boy bug that we do not implement, see The Ultimate Game Boy Talk - 46m 30s

Links

• Game Boy internals:

  • The Ultimate Game Boy Talk (33c3) by Michael Steil - you have to watch it!
  • bgb.bircd.org/pandocs - most of the things are here
  • gbdev.gg8.se - pandocs alternative
  • gbdev/awesome-gbdev - curated list of awesome Game Boy (Color) Development resources, tools, docs, related projects and open-source ROMs
  • pastraiser.com/gameboy_opcodes - instruction set
  • reddit.com/Game Boy (vblank) interrupt confusion - interrupts are disabled until the instruction after EI
  • Audio - we do not have audio (yet), but this can be useful:
    • gbdev.gg8.se/Gameboy sound hardware
    • github.com/PumpMagic/ostrich - Ostrich is a macOS media player app for playback of Game Boy Sound System files
    • aselker.github.io/gameboy-sound-chip
    • reddit.com/GB Emulator - SDL2 Audio Queue weird behavior

• Other emulators (github links):

  • Gekkio/mooneye-gb
  • mgba-emu/mgba
  • binji/binjgb
  • torch2424/wasmboy
  • Baekalfen/PyBoy
  • simias/gb-rs

• Other:

  • WebAssembly Is Fast: A Real-World Benchmark of WebAssembly vs. ES6 by Aaron Turner

License

“Swift plays Pokemon” is licensed under the Mozilla Public License 2.0. See LICENSE file for more information.