JoyBoy

Version 0.1

JoyBoy is a Game Boy emulator written in Go. It implements the documented LR35902 (Game Boy CPU) instruction set, ships an interactive debugger, and supports ROM-only (No MBC) cartridges. Rendering is currently performed a whole frame at a time at VBlank rather than scanline by scanline.

Current functionality

• CPU: documented LR35902 base and CB-prefixed opcode families are implemented, including the 0xCB prefix dispatch.
• Debugger: run/pause, single-step and held fast-step, breakpoints, register and timer display, and memory views for ROM, VRAM, RAM, OAM, I/O and HRAM. Includes tile, background-map, window-map and object viewers.
• Cartridges: ROM-only / No MBC cartridges are supported. No memory bank controller is implemented.
• Input: joypad support (see Controls).
• Rendering: background, window and object layers are reconstructed and uploaded as a complete frame when the PPU reaches VBlank (LY == 144).

Compatibility

• Tetris and Dr. Mario have been manually tested and run well.
• This is manual compatibility evidence only; JoyBoy is not a complete, hardware-accurate emulator yet and broad game compatibility should not be assumed.

Known limitations

• No MBC / bank switching support.
• No audio output.
• Whole-frame rendering instead of line-by-line (scanline) rendering.
• STOP is not handled and exits with an error; complete HALT-bug behavior is not implemented.
• Remaining PPU limitations around object priority, palettes, LCD-off behavior and timing.
• There is no ROM picker: the ROM path is hardcoded in Emulator.Restart in emulator/emulator.go.

Requirements

• Go 1.24 or newer
• OpenGL 3.3 capable graphics stack
• Native GLFW/OpenGL development dependencies (for example libgl1-mesa-dev and libglfw3-dev on Debian/Ubuntu, or the Homebrew equivalents on macOS)

Running

ROM files are not included. Use only legally obtained ROMs.

Build the binary and place a games/ folder in the same directory as the JoyBoy binary, containing the ROM you want to load (e.g. games/Tetris.gb):

make build      # build the JoyBoy binary
mkdir games     # next to the binary
# copy your legally obtained ROM there, e.g. games/Tetris.gb
./JoyBoy        # run in regular mode
./JoyBoy --debug  # run with the visual debugger

The ROM path is hardcoded in Emulator.Restart in emulator/emulator.go (./games/Tetris.gb), so change it there if you want to load a different game.

For development, make run and make dbg resolve ./games/... relative to the repository root:

make run        # run in regular mode
make dbg        # run with the visual debugger

Controls

Key	Action
Arrow keys	D-pad
A	A button
S	B button
K	Start
L	Select

Debugger controls

Key	Action
F3	Run
F4	Pause
F5	Single-step
F6	Fast-step while held
F7	Restart

Verification

• go test ./... compiles all packages; there is currently no automated test suite (no test files).
• make test runs an interactive ROM test harness (Blargg test ROMs) via go run . --test. It requires a graphics environment and is not a deterministic CI test.