node-mgbaHeadless Game Boy & GBA emulator for Node.js

Step frames, press buttons, read memory and capture the screen in Game Boy, Game Boy Color and GBA games, all from TypeScript. Powered by mGBA's libmgba core, built for AI agents, automation and research.

Get started

View on GitHub

A pixel-art screen with a small robot in a sunset landscape and a dialog box reading emu.controls.press('A')

Headless and fast

No window and no display server. Step frames far faster than real time, in-process or in a worker thread that never blocks your event loop.

Benchmarks

Frame-perfect input

Press, hold and release buttons, run input sequences, and advance exactly as many frames as you need.

Input & frame stepping

Direct memory access

Read and write Game Boy and GBA memory with no socket in between, or batch many reads into one call.

Reading & writing memory

Screen and audio capture

Grab raw frames or PNG/WebP, crop regions, and stream audio and video over WebSockets or straight into ffmpeg.

Screen capture & cropping

Plugins and schema DSL

Describe game structs declaratively and decode RAM into typed state. Ships with a Pokémon Red/Blue plugin to learn from.

Writing plugins

Built for agents

In-memory savestates for cheap branching, and a real-time worker loop for 24/7 livestreams.

Real-time & agent loops

Install

pnpmnpmyarn

pnpm add node-mgba

npm install node-mgba

yarn add node-mgba

Requires Node.js 20 or newer on x64 Linux or Windows. Bring your own ROMs.

A game in a few lines

import { Mgba } from 'node-mgba';

// Load a ROM (.gb, .gbc or .gba)
const emu = await Mgba.load('./game.gb');

// Advance a second of game time, then press A
await emu.controls.tick(60);
await emu.controls.press('A');

// Read memory and grab the screen
const playerX = await emu.memory.read8(0xd362);
const png = await emu.screen.toPng();

await emu.close();

Continue with the guide →

Where it came from

node-mgba started as the emulator layer for Gemini Plays Pokémon, the 24/7 Twitch stream where Gemini plays Pokémon on its own. It's the same code the stream runs on, packaged so you can build your own game-playing agents. Read The Making of Gemini Plays Pokémon, or watch the agent think in the web viewer.