Beginner guide
By the end of this page you will have run a CHIP-8 program in a window, pressed keys on the CHIP-8 keypad and printed the screen as text in your terminal.
What you need
- chip8 built from source. See Install.
- A terminal opened in the
chip8source folder. curland an internet connection, to download the test ROMs.
Get some ROMs
A ROM is a file holding a CHIP-8 program. chip8 does not come with any. The repository has a script that downloads the free Timendus chip8-test-suite ROMs.
./tests/roms/fetch_roms.shThe script prints one line per file and a summary:
fetching 1-chip8-logo.ch8
fetching 2-ibm-logo.ch8
fetching 3-corax+.ch8
fetching 4-flags.ch8
fetching 5-quirks.ch8
fetching 6-keypad.ch8
fetching 7-beep.ch8The last line, starting with done: 7 ROMs in, names the folder they were saved to: tests/roms.
Good to know
Use ROMs you are allowed to use: test ROMs like these, homebrew released by its author, or programs you wrote. Many CHIP-8 programs are in the public domain, but check before you download.
Run your first ROM
Start the IBM logo ROM:
bash./build/chip8 tests/roms/2-ibm-logo.ch8A 768×384 window opens. Its title is
chip8 -followed by the ROM path. The IBM logo appears.Press Space to pause, and Space again to continue. This ROM shows a still picture, so you will not see a difference, but the program stops and resumes.
Press Esc to quit. Closing the window does the same.
Try the keypad
CHIP-8 has a 16-key keypad labelled 0 to F. chip8 maps it to the left side of your keyboard:
CHIP-8 Keyboard
1 2 3 C 1 2 3 4
4 5 6 D → Q W E R
7 8 9 E A S D F
A 0 B F Z X C VThe mapping follows key positions, not letters, so it also works on non-QWERTY layouts: use the keys in the same physical places.
Start the keypad test:
bash./build/chip8 tests/roms/6-keypad.ch8The ROM shows a menu with three tests.
Press 1 to choose the first test. It draws the keypad on screen.
Press and hold any mapped key, for example W (CHIP-8 key
5). The matching key on screen changes while you hold it.Press Esc to quit.
Hear the beep
./build/chip8 tests/roms/7-beep.ch8This ROM beeps an SOS pattern and shows a speaker icon while the sound plays. Add --mute before the ROM name to run without sound.
Print the screen as text
chip8_run_rom runs a ROM with no window for a fixed number of frames, then prints the screen. It is how the test suite checks results.
./build/chip8_run_rom tests/roms/2-ibm-logo.ch8 --frames 120The first line shows the ROM, the settings and the final CPU state. Below it is the 64×32 screen drawn with ## for lit pixels, inside a border:
+--------------------------------------------------------------------------------------------------------------------------------+
| |
| |
| |
| |
| |
| |
| |
| |
| ################ ################## ########## ########## ## ## |
| ## ## |
| ################ ###################### ############ ############ ## |
| |
| ######## ###### ###### ########## ########## ## ## |
| ###### |
| ######## ############## ############## ############## ## |
| ## |
| ######## ############## ###### ############## ###### |
| ## |
| ######## ###### ###### ###### ########## ###### |
| ###### |
| ################ ###################### ########## ###### ########## ## |
| #### |
| ################ ################## ########## ## ########## ###### |
| |
| |
| |
| |
| |
| |
| |
| |
| |
+--------------------------------------------------------------------------------------------------------------------------------+What you learned
- ROMs are not bundled;
tests/roms/fetch_roms.shdownloads free test ROMs. ./build/chip8 rom.ch8opens the window. Space pauses and Esc quits.- The keypad is the
1234/QWER/ASDF/ZXCVblock. chip8_run_romruns a ROM without a window and prints the screen.