DHIVA LABS · LEARN

Appearance

Beginner guide ​

By the end of this page you will have run a Game Boy ROM in a window, learned the controls, and run a CPU test from the terminal.

What you need ​

  • gameboy built from source. See Install.
  • A terminal opened in the gameboy source folder.
  • git, curl and an internet connection, to download the test ROMs.

Get a ROM you may use ​

gameboy does not come with any ROMs. The repository has a script that downloads two free sets of test ROMs: blargg's Game Boy test suites and dmg-acid2, a graphics test.

bash
./tests/roms/fetch_roms.sh

When it finishes, the script checks the download of dmg-acid2.gb and prints a line starting with done:. The files are in tests/roms.

WARNING

Only run ROMs you have the right to use: these test ROMs, homebrew released by its author, or dumps you made from cartridges you own. Commercial game ROMs downloaded from the internet are not yours to use.

Run your first ROM ​

  1. Start the graphics test:

    bash
    ./build/gameboy tests/roms/dmg-acid2.gb

    A 640×576 window opens. Its title is gameboy - followed by the title stored in the ROM.

  2. Look at the picture. dmg-acid2 draws a smiling face in four shades of green. Every part of the face tests one graphics feature, so a complete, tidy face means the graphics work.

  3. Press Esc to quit. Closing the window does the same.

Learn the controls ​

Game Boy buttonKey
D-padArrow keys
AX
BZ
StartEnter
SelectRight Shift

Two more keys control the emulator: hold Tab for turbo, and press Esc to quit.

Play a homebrew game ​

Homebrew games are new Game Boy programs released by their authors. The project has been checked with two of them: Libbet and the Magic Floor and Adjustris. Download a homebrew ROM from its author's page, then run it the same way:

bash
./build/gameboy path/to/game.gb

Three options are useful when you play:

  • --scale 6 makes the window bigger. The default is 4.
  • --mute turns sound off.
  • --turbo runs as fast as your computer allows for the whole session. Holding Tab does the same for as long as you hold it. Sound is dropped during turbo.

WARNING

gameboy does not write battery saves. A game that saves to its cartridge starts from scratch each time you run it.

Run a CPU test from the terminal ​

gb_run_rom runs a ROM with no window. Blargg's test ROMs report their result as text, which the runner prints.

bash
./build/gb_run_rom tests/roms/gb-test-roms/cpu_instrs/individual/01-special.gb

The runner prints the name of the loaded ROM, then the text the test sends, which ends in Passed, then a line with the number of cycles and frames it ran. Its exit status is 0 for a pass, 1 for a fail and 2 if the test never gave a verdict.

What you learned ​

  • ROMs are not bundled; tests/roms/fetch_roms.sh downloads free test ROMs.
  • ./build/gameboy rom.gb opens the window. Arrows, X, Z, Enter and Right Shift are the buttons.
  • Tab is turbo and Esc quits.
  • gb_run_rom runs test ROMs without a window and reports pass or fail.

Next steps ​