gameboy

An accurate gameboy emulator written in C from scratch.

development

In order to run the emulator, you need to have cmake, a build system like ninja and a C compiler. SDL2 is included as a submodule and will be compiled along with the project.

1. Clone the repository

git clone --recurse-submodules git@github.com:Jabolol/gameboy.git .

2. Add the ROMs directory with the ROMs to be loaded in the web version

mkdir ROMs && cp /path/to/rom.gb ROMs

3. Compile the project

cmake -B build -G Ninja && cmake --build build

4. Run the emulator

./build/gameboy /path/to/rom.gb

features

• Bus (Memory Management)
• CPU
• PPU (Graphics)
• Game Boy Color support (partial / work in progress)
• Input (Joypad)
• Timer
• Interrupts (V-Blank, LCD, Timer, Serial, Joypad)
• MBC1 - MBC7 (Memory Bank Controllers 1-7)
• Save States (.sav files)
• Sound (Square Wave, Wave, Noise)
• Web version at gameboy.deno.dev

controls

• Arrow Keys - D-Pad
• Z - A
• X - B
• U - Volume Up
• D - Volume Down
• Tab - Select
• Enter - Start
• Q - Quit

web version

The emulator is also available as a web version using emscripten and deno. In order to run the web version, you need to have deno installed.

game selection

The web version includes 26 preloaded games. Append ?game=${game} to the URL to load a specific game. If no game is specified, a random game will be loaded.

The full list of games can be found in www/utils/gameLoader.ts.

ui controls

The web interface includes a control dock with the following features:

• Canvas Scale - Cycle between 1x, 2x, and 3x zoom levels (defaults to 1x on mobile, 3x on desktop)
• Volume Control - Adjust audio volume from 0 to 100% in 10% increments
• Theme System - Three available themes: light, dark, and auto (automatically detects the game's color palette by sampling canvas pixels and switches between light/dark themes accordingly in real-time)
• Tiles Viewer - Toggle visibility of internal gameboy tiles used to render the current frame
• Persistent State - All settings (scale, volume, theme, tiles) are saved to localStorage and restored on page load

running locally

Tip

To enable google analytics, set the GA4_MEASUREMENT_ID environment variable to your GA4 measurement ID.

The web version will bundle the ROMs available at ROMs directory and serve them at http://localhost:5173.

deno task --cwd www dev

screenshots

Legend of Zelda, The - Link's Awakening

Pokemon - Yellow Version - Special Pikachu Edition

Pokemon - Crystal Version

Dr. Mario

Mega Man - Dr. Wily's Revenge

Contra - The Alien Wars

Kirby - Dream Land

Kirby - Dream Land 2

Tetris

Super Mario Land

Super Mario Bros. Deluxe

Galaga

resources

• Gameboy CPU Manual: A comprehensive guide to the Gameboy CPU.
• Gameboy Opcodes: List of all opcodes for the Gameboy CPU.
• Gameboy Pan Docs: A detailed guide to the Gameboy hardware.

license

This project is licensed under the MIT License - see the LICENSE file for details.