Reference
Every option, key and exit code of gameboy and gb_run_rom.
gameboy options
text
gameboy [options] <rom.gb>| Option | Default | What it does |
|---|---|---|
--scale N | 4 | Window scale factor. 4 gives 640×576. Values below 1 become 1. |
--turbo | off | Runs uncapped for the whole session. Sound is dropped. |
--mute | off | Disables audio. |
--frames N | run until quit | Exits after N frames. For automated tests. |
--help, -h | Prints the usage text. |
If you name more than one ROM, the last one is used. An unknown option or a missing ROM prints the usage text.
Key bindings
| Key | Action |
|---|---|
| Arrow keys | D-pad |
| X | A |
| Z | B |
| Enter | Start |
| Right Shift | Select |
| Tab (hold) | Turbo |
| Esc | Quit |
Keys are matched by physical position and cannot be remapped.
gameboy exit codes
| Code | Meaning |
|---|---|
0 | Normal exit |
1 | The ROM could not be loaded, or SDL failed to start |
2 | Bad command line, or --help |
Messages
| Message | Meaning |
|---|---|
error: cannot open ROM: … | The file is missing or unreadable. |
error: ROM too small to have a header: … | The file is shorter than a Game Boy header (336 bytes). |
error: unsupported cartridge type 0x… (ROM-only/MBC1/MBC3 only) | The cartridge type is not emulated. |
warning: no audio device (…), running silent | No audio output could be opened. |
CPU stopped (STOP or illegal opcode) at PC=0x… | The program halted the CPU for good. gameboy exits. |
Supported cartridge types
Header byte 0x147 | Type |
|---|---|
0x00, 0x08, 0x09 | ROM-only |
0x01, 0x02, 0x03 | MBC1 |
0x0F to 0x13 | MBC3, banking only (no real-time clock) |
gb_run_rom options
text
gb_run_rom <rom.gb> [--max-cycles N] [--frames N] [--screenshot PATH]
[--press BUTTON:FRAME]...| Option | Default | What it does |
|---|---|---|
--max-cycles N | 800000000 | Cycle budget before giving up, about 190 seconds of emulated time. |
--frames N | none | Stops after N frames instead of waiting for a verdict. |
--screenshot PATH | none | Saves the final screen as a BMP file. |
--wav PATH | none | Saves the sound output as a WAV file. |
--press BUTTON:FRAME | none | Presses a button at that frame, released 8 frames later. Repeatable. |
Button names: right, left, up, down, a, b, select, start.
| Exit code | Meaning |
|---|---|
0 | The ROM reported Passed, or a --frames run finished |
1 | The ROM reported Failed, or a file could not be read or written |
2 | Timeout with no verdict, or a bad command line |
Test scripts
| Script | What it does |
|---|---|
tests/roms/fetch_roms.sh | Downloads blargg's test ROMs and dmg-acid2.gb into tests/roms. |
tests/run_tests.sh [BUILD_DIR] | Runs the suite. BUILD_DIR defaults to build. |
tests/run_tests.sh --update [BUILD_DIR] | Rewrites tests/expected/*.sha256. |
| Environment variable | Used by | What it does |
|---|---|---|
GB_TEST_ROMS_REF | fetch_roms.sh | Fetches another commit or ref of the blargg test ROM mirror instead of the pinned one. |
Hardware facts
| Item | Value |
|---|---|
| Screen | 160×144 pixels, four shades |
| Frame rate | About 59.73 frames per second |
| Sound | 48 kHz stereo |