Gearboy is a free, open-source Game Boy, Game Boy Color and Super Game Boy emulator from Nacho Sánchez. Its desktop application runs on Windows, macOS, Linux and BSD, combining gameplay with a debugger and an MCP server. A separate Libretro core runs inside compatible frontends such as RetroArch.
Opening a cartridge image
You can open a ROM from the file menu, drag it onto Gearboy or pass its path on the command line. It accepts Game Boy cartridge formats and ZIP archives. Hardware and mapper options control the handheld model and cartridge memory controller. A boot ROM is optional.
Softpatching applies a matching IPS patch beside the ROM when the game loads. The cheats window accepts Game Genie and GameShark codes, with descriptions and individual enable switches. It also imports RetroArch cheat files. Invalid entries cannot activate.
Playback beyond the cartridge save
Gearboy preserves battery-backed cartridge RAM and can save or restore complete emulation states. State slots show the cartridge name and a preview; separate commands work with explicit state files. Loading a state returns execution to that snapshot, beyond the game’s own save mechanism.
Rewind moves through earlier snapshots. Run-ahead instead computes extra frames speculatively to reduce input delay, with additional CPU work. State operations cannot run while a boot ROM executes. Desktop link sessions also prevent state loading, rewind and run-ahead.
Adapting the screen and controls
Video options include monochrome palettes, LCD ghosting and dot-matrix effects. Gearboy’s shader system reads presets that describe GLSL processing passes. Each pass can filter or scale its input, and the final pass supplies the picture on the screen. Presets can expose sliders or checkboxes for their parameters.
Keyboard and gamepad settings map physical controls to the handheld’s directions, action buttons, Start and Select. Direction input can use a controller’s D-pad, analog stick or both. For compatible tilt cartridges, mouse movement, controller sensors or an analog stick can supply motion input.
Connecting two handhelds locally
The desktop Link Cable feature connects two Gearboy instances through a shared session number. Each instance runs its own game, and the emulators exchange the serial data that a physical cable would carry. Separate application or portable-data folders keep their saves and settings apart.
Barcode Boy emulation supplies barcode input to compatible games. You choose a card or custom digits, then trigger a scan when the game requests one. The reader cannot operate during a link-cable session.
Following instructions through the debugger
The debugger can pause execution, step through instructions or frames and continue until a breakpoint. Execution breakpoints stop at an address; memory breakpoints stop on reads or writes. The processor view exposes registers and flags, while the disassembler translates code into instructions.
Gearboy loads matching symbol files automatically or accepts a separate symbol file. These labels connect addresses to names during navigation. Other inspection windows work on different parts of the same running machine:
- The memory editor reads and changes bytes in cartridge RAM, video memory and other memory areas.
- Video viewers show tiles, sprites, backgrounds and palettes from the graphics state.
- The IO inspector exposes hardware registers, while audio inspection shows sound-channel state.
The trace logger records CPU instructions and hardware events that you select. Its filters select streams such as interrupts or serial transfers. A function profiler separately reports call counts and inclusive or exclusive cycle totals.
External tools share the live machine
Gearboy’s MCP server exposes execution, memory, breakpoint, hardware and controller tools to compatible AI clients. Requests act on the same state as the interface, so a memory edit or pause affects the open game.
With standard input/output transport, the client launches Gearboy and communicates through pipes. HTTP transport instead connects to an independently running instance. A headless mode runs these tools without the graphical window. Multiple clients still share one emulator instance and its state.
Capturing frames and sound activity
Gearboy saves screenshots as PNG and records video with audio into AVI files. Recording controls choose image scaling, aspect ratio and quality before capture. A shader preset can instead determine the recording’s rendered output.
The VGM recorder logs Game Boy sound-register activity and its timing into a music file. Its start and stop controls delimit the interval of emulation to record.
