Reference

Every option, key and exit code of chip8 and chip8_run_rom.

chip8 options

chip8 [options] <rom.ch8>

Option	Default	What it does
--ips N	540	Instructions per second. Values below 60 become 60.
--scale N	12	Window scale factor. 12 gives 768×384. Values below 1 become 1.
--profile P	vip	Quirk profile: vip or modern.
--mute	off	Disables the beeper.
--frames N	run until quit	Exits after N 60 Hz frames. For automated tests.
--screenshot PATH	none	Saves a BMP screenshot before exiting.
--help, -h		Prints the usage text.

If you name more than one ROM, the last one is used. An unknown option, an unknown profile or a missing ROM prints the usage text.

Key bindings

Key	Action
Space	Pause or resume
Esc	Quit
1 2 3 4	CHIP-8 keys 1 2 3 C
Q W E R	CHIP-8 keys 4 5 6 D
A S D F	CHIP-8 keys 7 8 9 E
Z X C V	CHIP-8 keys A 0 B F

Keys are matched by physical position, so the block stays in the same place on any keyboard layout.

chip8 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

Quirk profiles

Behaviour	vip	modern
8XY1, 8XY2, 8XY3	Reset VF to 0	Leave VF alone
8XY6, 8XYE	Shift VY into VX	Shift VX in place
FX55, FX65	I = I + X + 1 after	I unchanged
BNNN	Jump to NNN + V0	Jump to NNN + VX
DXYN timing	Waits for the 60 Hz tick	No wait
DXYN edges	Start wraps, pixels clip	Same
FX0A	Completes on key release	Same

chip8_run_rom options

chip8_run_rom <rom.ch8> [--frames N] [--ips N] [--profile vip|modern]
              [--seed N] [--poke ADDR=VAL]... [--key K:DOWN:UP]... [--bmp PATH]

Option	Default	What it does
--frames N	480	Number of simulated 60 Hz frames to run.
--ips N	540	Instructions per second.
--profile P	vip	Quirk profile: vip or modern.
--seed N	fixed	Seed for the random-number instruction, so runs repeat exactly.
--poke ADDR=VAL	none	Writes one byte to memory after the ROM loads. Repeatable.
--key K:DOWN:UP	none	Presses hex key K at frame DOWN and releases it at frame UP. Repeatable.
--bmp PATH	none	Also saves the final screen as a BMP file.

The runner prints a status line (ROM, frames, speed, profile, and the final PC, I, delay timer and sound timer), a WARNING line if an unknown opcode was met, then the screen as text.

It exits with 0 on success, 1 if the ROM could not be loaded or the BMP could not be written, and 2 for a bad command line.

Test scripts

Script	What it does
tests/roms/fetch_roms.sh	Downloads the Timendus test ROMs 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/*.txt.

Environment variable	Used by	What it does
TIMENDUS_REF	fetch_roms.sh	Fetches another branch, tag or commit of the test suite instead of the pinned one.

Limits

Item	Value
Screen	64×32 pixels, one colour
Memory	4096 bytes; ROMs load at 0x200
Largest ROM	3584 bytes
Timers	60 Hz
Beep	440 Hz square wave

Next steps

• Speed, quirks and screenshots
• Troubleshooting and FAQ