This project is yet another Gameboy + Gameboy Color emulator written entirely in TypeScript. The goal of this project was to write core of the emulator in TypeScript and then port the emulation to all platforms - web, desktop and mobile.
You can checkout running Emulator in web on GitHub pages here
It's just fun little project done on the side. Ultimate goal is to support MBC0, MBC1, MBC2, sound, most possible accurate timing, saving and loading emulation state to run all Pokemon ROMs.
Theare are three four main directories in repository:
core - holds Emulator source code for every component such as CPU, Memory, GPU, Timers etc. This is completely separatered from any kind of rendering environment such as web / mobile / desktop. Emulator exposes events or callback allowing to retrieve events such as draw frame or input handlers.
desktop - this is desktop GUI implementation for Emulator. It uses core package for emulation and currently is running via Electron on desktop. Releases currently are build only for Linux since I am running Ubuntu.
mobile - this is mobile GUI implementation for Emulator. It ueses core pacakge for emulation and currently is running via Ionic framework on mobile. Releases currently are build only for Android since I do not own IOS device.
website - this is web GUI implementation for Emulator. It uses core package for emulation and currently is running via HTML5 canvas on web. Release is available under GitHub page link here. It's tested on Firefox and Chromium.
Each of these directories contains it's own README.md file. Please refer to them for more documenation on each component including npm scripts description, directory structure, etc.
| Feature | Status | Addtional description |
|---|---|---|
| CPU | ✔️ | Done, CPU running at 4.194304 MHz |
| CPU + Memory Timing | ❌ | There is problem with passing instr_timing test tests. The issue arrises from the fact that each CPU OP Code is retuning number of cycles by the end of execeution and ticks are incremented once at the end. Correct implementation would increase ticks at each memory read / write so that it could be synced correectly |
| Timer - DIV | ✔️ | Done |
| Timer - TIMA | ✔️ | Done |
| Joypad | ✔️ | Done |
| GPU - Classic | ✔️ | GPU is only not passing timing test in DMG_ACID test ROM. It's due to timing implementation issues mentioned earlier in CPU |
| GPU - Color | ❌ | Not started at all |
| MBC 0 | ✔️ | Done, Tetris and Dr Mario both launches |
| MBC 1 | ❌ | Coming soon |
| MBC 2 | ❌ | Coming soon |
| Sound | ❌ | Not started at all, coming after MBC1 and MBC2 support + timing issues resolved |
| Saving state | ❌ | Not started at all, coming after sound support |
| Loading state | ❌ | Not started at all, coming after sound support |
| 60 FPS constant | ❌ | It's not an issue on web or desktop but on mobile devices there are sometimes drops to under 40 FPS. Consider adding cache for graphics so that background + tiles are re-rendered only when they are changed. |
| Upscaling | ✔️ | Working, scaling up to 5 times original resolution. Algorithm is pretty dumb but it is enough for now |
This section is to show emulator compability status by running E2E Tests for various components such as CPU or GPU. Currently those tests are run manually, but in future those will run automatically by comparing hash checksum of VRAM content with baseline hash.
01-special:
02-interrupts:
03-op sp,hl:
04-op r,imm:
05-op rp:
06-ld r,r:
07-jr,jp,call,ret,rst:
08-misc instrs:
09-op r,r:
10-bit ops:
11-op a,(hl):
It's not 100% accurate due to incorrect CPU / Memory timing
- https://www.youtube.com/watch?v=HyzD8pNlpwI - ultimate Gameboy talk
- http://marc.rawer.de/Gameboy/Docs/GBCPUman.pdf - Gameboy CPU Manual
- https://github.com/trekawek/coffee-gb/ - easy to read Gameboy Emulator in Java
- https://github.com/juchi/gameboy.js - Gameboy in pure JS
- https://github.com/nakardo/node-gameboy#readme - Gameboy in pure JS and for Node
- https://www.youtube.com/watch?v=B7seNuQncvU - creating Gameboy emulator in Rust - talk
- http://imrannazar.com/GameBoy-Emulation-in-JavaScript:-The-CPU - article about creating Gameboy emulator in JS
- https://gbdev.gg8.se/wiki/articles/Main_Page - Gameboy development wiki
- https://gekkio.fi/files/gb-docs/gbctr.pdf - Gameboy technical reference PDF
- https://www.pastraiser.com/cpu/gameboy/gameboy_opcodes.html - HTML Table with OP Code instruction set including CPU cycles, memory timing, etc - really usefull
- https://gbdev.gg8.se/files/roms/blargg-gb-tests/ - test ROMs
- https://wornwinter.wordpress.com/2015/02/14/adventures-in-gameboy-emulation-part-2-the-cpu/ - step by step series for Gameboy Emulator in C++
- https://realboyemulator.wordpress.com/2013/01/03/a-look-at-the-game-boy-bootstrap-let-the-fun-begin/ - Gameboy BOOT ROM explained instruction by instruction - really usefull at the beggining when you need to debug if your emulator is behaving correctly on BOOT ROM
- https://github.com/retrio/gb-test-roms/tree/master/cpu_instrs - Blargg's test ROM repo having one uber ROM for all tests and splitted by tests smaller ROMs fitting within MBC0
- https://github.com/Gekkio/mooneye-gb - well document and accurate Gameboy Emulator in Rust
- https://gbdev.io/pandocs/ - Legendary Pan Docs
- http://www.codeslinger.co.uk/pages/projects/gameboy/beginning.html - amazing step by step article on how to implement each subsytem
- https://github.com/juchi/gameboy.js/ - easy to read Gameboy Emulator in JS.