Naive GameBoy

A Gameboy emulator written in JS.

Demo

Motivation

The purpose of this project is mostly educational. The goal is to make this project a good reference for others who are learning about GameBoy or planning to create their own GameBoy emulator. We aim at making the code simple to understand as much as possible, and at the same time, accurate enough to emulate most of the behaviour correctly.

Run in the Browser

Try it out here. The web app is built under folder /docs and hosted by Github Pages.

Please note that due to copyright protection, only the Blargg's test roms are available to run in the web app. You will need to supply you own roms if you want to run anything else.

Run locally in the browser:

npm run web

Keys:

Action	Key
B	Z
A	X
UP,DOWN,LEFT,RIGHT	↑ ↓ ← →
START	Enter
SELECT	Space

Run in the Terminal (headless mode)

npm run headless

Note that in this mode, there is NO graphic output. In the terminal, you will only see the serial output from FF01 I/O port (FF01 - SB - Serial transfer data (R/W)).

Test

npm run test

This will run the test automatically in headless mode. We use Jest testing framework to run tests against Blargg's test roms. For deatils, check the testing code under __test__

Test Result

Blargg's test roms

Test	Result
cpu_instrs	✔️
instr_timing	✔️
mem_timing1	✔️
mem_timing2	✔️
interrupt_time	❌ (require CGB support)
dmg_sound	✔️
halt_bug	✔️
oam_bug	❌

Roadmap

Milestone 1.0:

• Pass halt_bug test roms
• Pass oam_bug test roms
• Make MBC1 implementation robust
• Support MBC2, MBC3
• Fix WAVE channel sound issue
• Support noise channel
• Test more game roms

Milestone 2.0:

• Enable CGB support
• Pass interrupt_time test
• Interative web UI for debugging

How to Contribute

1. Make changes and see live update in browser npm run web
2. Make sure the tests pass. npm run test
3. Build the web application. npm run build

Folder Structure

/src
 The emulator source code. The emulator itself is a class and can be imported in any web applications.
 
/testROMs
 All the Blargg's test rooms
 
/web
 A web app imports ngb class
 
/docs
 The build artifact of the web app. It also hosts the Github Page

Reference

• BinjGB. The emulator I refered most to when working on NaiveGB
• Pan Docs (new version)
• GhostSonic's insights on APU
• An explanation of dmg_sound test
• GameBoy sound hardware
• OP Codes
• GameBoy Programming Manual
• Nitty Gritty Gameboy Cycle Timing
• Complete Technical Reference