DHIVA LABS · LEARN

Appearance

Play ROMs ​

How to tell whether a ROM will run, and the options you use while playing.

Which ROMs run ​

gameboy runs original Game Boy (DMG) ROMs whose cartridge type is one of these:

Cartridge typeSupport
ROM-onlyYes
MBC1Yes
MBC3Bank switching only. The real-time clock is not emulated.
MBC5 and laterNo

Many early games are ROM-only or MBC1. Much homebrew ships with an MBC3 header and runs, as long as it does not depend on the clock.

A ROM with another cartridge type stops at once with:

text
error: unsupported cartridge type 0x19 (ROM-only/MBC1/MBC3 only)

The number after 0x is the type byte from the ROM's header; yours may differ.

Game Boy Color games are not supported. A ROM that runs on both systems starts in original Game Boy mode.

WARNING

Use only ROMs you have the right to use: homebrew released by its author, test ROMs, or dumps you made from cartridges you own.

Start a ROM ​

bash
./build/gameboy game.gb

Options go before or after the ROM name.

Make the window bigger ​

The Game Boy screen is 160×144 pixels. --scale multiplies it. The default is 4, a 640×576 window.

bash
./build/gameboy --scale 6 game.gb

Turn off the sound ​

bash
./build/gameboy --mute game.gb

If your computer has no working audio device, gameboy prints warning: no audio device and runs silently.

Skip slow parts with turbo ​

Hold Tab to run as fast as your computer allows; release it to return to normal speed. To run the whole session uncapped, start with --turbo.

Sound is dropped while turbo is on.

Saving ​

gameboy does not store battery saves or save states. Progress a game keeps on its cartridge is lost when you quit. Leave the emulator running if you want to come back to a game later in the day.

When a game stops by itself ​

If the window closes and the terminal shows:

text
CPU stopped (STOP or illegal opcode) at PC=0x0150

the program executed a STOP instruction or an opcode the real CPU locks up on. The address at the end varies. This usually means the ROM is damaged, needs an unsupported cartridge type, or is a Game Boy Color-only program.

Known picture and sound limits ​

  • A handful of games change the picture in the middle of a scan line for split-screen effects. gameboy draws a line at a time, so those effects can shear.
  • Sound is right for games, but some rare hardware edge cases are simplified.

Next steps ​