GBZ80 Damage

Game Boy (DMG) emulator written in TypeScript: full CPU, PPU, APU, timers, interrupts, MBC1/MBC3 cartridges, and Joypad — playable in the browser or in the terminal.

Quick start

yarn install

Browser (recommended)

yarn web:build
yarn web:serve

Open http://localhost:8000/web/index.html, then drop a .gb/.gbc file anywhere on the page (or use the file picker). No game is bundled — bring your own ROM dump.

The browser frontend is also deployed automatically to GitHub Pages after pushes to main. Enable Settings → Pages → Source: GitHub Actions once in the repository settings.

• Canvas at 2x by default (fit / 3x / 4x available), 4 palettes, scanlines, fullscreen, touch-friendly buttons.
• Sound via Web Audio (starts on first key/click, M mutes).
• Battery saves persist in localStorage; Reset/ROM-switch/tab-close all persist first. Saves can also be downloaded as .sav or wiped.
• Keyboard: arrows/WASD d-pad, X/K B, Z/J A, Enter start, Shift select, P pause, M mute.

Terminal

yarn play <rom.gb> [ascii|hires]

ASCII (80×36) or hires quadrant (80×72, auto-selected on tall terminals) rendering at the original ~59.7 fps. Keys: arrows, X A, Z B, Enter start, Backspace select, P pause, Q quit. Battery saves are written next to the ROM as <rom>.sav.

Tests

yarn test        # vitest, 190 tests

Covers CPU registers/flags, 8/16-bit ALU, shifts/bits, memory bus, timer, interrupts, cartridge/MBC, PPU layers, APU channels (including a measured 440 Hz pitch test), joypad, SRAM save round-trip, and renderers.

Layout

• src/cpu/ — registers, instruction set + step(), 64 KiB bus, timer, interrupts, joypad, MBC1/MBC3 cartridges
• src/ppu/ — scanline renderer (background, window, sprites), 160×144
• src/apu/ — 4 sound channels (pulse+sweep, pulse, wave, noise), mixer
• src/emulator.ts — platform-agnostic core: boot, frame loop (17556 M-cycles @ 59.7 Hz), save handling
• src/web/ — browser frontend (canvas, Web Audio, localStorage saves)
• src/terminal/ — ASCII/hires terminal frontend
• src/main.ts — terminal entry point

Accuracy notes

• CPU passes its opcode/flag unit tests; timings follow gb-opcodes in M-cycles.
• APU sequencer runs off DIV bit 12 (512 Hz); DAC curve, HPF, and mixer follow PanDocs; pitch verified by measurement.
• No CGB/SGB features, no RTC ticking (stubbed), no link cable, no boot ROM (DMG post-boot state is set directly).

Docs

https://gbdev.io/pandocs/Specifications.html

https://gbdev.io/gb-opcodes/optables/

https://gbdev.io/gb-asm-tutorial/