GB.js is an accuracy-focused TypeScript library for Game Boy, Game Boy Color, and Game Boy Advance emulation. It separates deterministic emulation cores from presentation, storage, and input policy, so the same package can power browser players, cartridge tools, automated tests, and custom frontends.
The package includes ESM, CommonJS, browser bundles, and TypeScript declarations. ROM and BIOS data are never bundled: applications must supply legally obtained images. The separate online Game Boy emulator demonstrates the library in a complete browser player without turning the package documentation into a game page.
View GB.js on GitHub for source code, tests, release notes, and detailed subsystem status.
Install GB.js
npm install @rawify/gb
The root entry provides cartridge inspection. Dedicated subpaths expose the Game Boy and Game Boy Advance systems:
import { parseROMHeader } from '@rawify/gb';
import { DMGBus } from '@rawify/gb/gb';
import { GameBoyAdvanceSystem } from '@rawify/gb/gba'; Node.js 20 or newer is required. Browser applications can use the ESM build directly, while bundlers resolve the package exports automatically.
Inspect a Cartridge
Header inspection is independent of the emulation runtime. parseROMHeader() validates the Nintendo logo and header checksum, detects the platform, and returns the decoded cartridge metadata:
import { parseROMHeader } from '@rawify/gb';
const bytes = new Uint8Array(await file.arrayBuffer());
const detected = parseROMHeader(bytes);
console.log(detected.model);
console.log(detected.header.title); Lower-level parseGameBoyHeader() and parseGameBoyAdvanceHeader() functions accept { strict: false } for diagnostics and homebrew tooling. Strict validation should remain enabled when a program must reject malformed or misidentified images.
Run a Game Boy Advance System
import { GameBoyAdvanceSystem } from '@rawify/gb/gba';
const gba = new GameBoyAdvanceSystem({ rom: romBytes });
gba.setButton('a', true);
gba.runCycles(1024);
const frame = gba.frameBuffer;
const audio = gba.drainAudio(); Without a BIOS image, the CPU starts at the cartridge entry point and provides high-level emulation for a limited set of common BIOS calls. Supplying bootROM starts from the reset vector and disables that fallback. Save memory, real-time-clock state, keypad input, video frames, and audio buffers remain under application control.
Architecture
GB.js is organized around explicit clocks and memory buses rather than browser animation timing. The Game Boy Advance core coordinates an ARM7TDMI CPU, DMA, timers, interrupts, graphics, audio, keypad input, cartridge save devices, and RTC hardware through a deterministic scheduler. The Game Boy core contains the SM83 instruction set, cartridge controllers, LCD timing, DMA, timers, audio, serial transfer, and DMG/CGB memory behavior.
This architecture makes execution reproducible and allows individual components to be tested without a visual frontend. The package is nevertheless under active development. Hardware behavior is implemented incrementally, and the repository documents known accuracy limits and unsupported peripheral modes. Applications should pin a tested package version instead of assuming complete compatibility with every title.
Browser Integration
The interactive player uses the same ESM package entry as an application would. It adds only frontend policy: drag-and-drop loading, keyboard and gamepad input, Web Audio output, fullscreen display, and local save persistence. Game Boy, Game Boy Color, and Game Boy Advance files are accepted. A Game Boy Advance BIOS can be supplied when a title requires behavior beyond the available BIOS fallback.
GB.js on npm provides the published package, while the GB.js source repository contains the implementation, tests, detailed subsystem status, and license.
References
- [ARM1996]ARM Limited, ARM Architecture Reference Manual, ARMv4 and ARMv4T architecture documentation.
- [Nintendo]Nintendo, official Game Boy Advance programming and hardware documentation.