Troubleshooting and FAQ
Building
CMake cannot find SDL2
The SDL2 development files are missing. On Debian or Ubuntu, install them and configure again:
sudo apt install libsdl2-devOn Windows, install SDL2 with vcpkg and pass the vcpkg toolchain file to CMake, as shown in Install.
The compiler rejects the code
chip8 is written in C++20. Use a recent GCC, Clang or Visual Studio 2022.
Running
chip8 prints its usage text and exits
The command line was not understood. Common causes: no ROM file was named, an option was misspelt, or --profile was given something other than vip or modern. An error: line above the usage text names the problem.
error: cannot open ROM
The file does not exist at that path or cannot be read. Check the path. Put it in quotes if it contains spaces or a +, as in "tests/roms/3-corax+.ch8".
error: ROM too large
Classic CHIP-8 programs load at address 0x200 in 4096 bytes of memory, so a ROM can be at most 3584 bytes. A bigger file is usually a SUPER-CHIP or XO-CHIP program, which chip8 does not run.
warning: unknown opcode appears when I quit
The ROM used an instruction chip8 does not implement. That is typical of SUPER-CHIP or XO-CHIP ROMs. They are out of scope.
The game is too slow or too fast
Change the instruction speed with --ips. The default is 540. Try 700 to 1000 for ROMs tuned for other interpreters. See Change the speed.
The graphics are wrong, or the game hangs
The ROM probably expects a different interpreter family. Run it with --profile modern. See Pick a quirk profile.
A key press does nothing until I let go
That is how the wait-for-key instruction (FX0A) works on the original machine, and chip8 copies it: the key counts when it is released.
There is no sound
Check that you did not pass --mute and that your system has a working audio output. If no audio device can be opened, chip8 keeps running without sound.
SDL_Init: error at startup
SDL could not start video or audio. On a machine with no sound system, run with --mute, which skips audio. chip8 needs a graphical desktop to open its window; over a plain SSH session, use chip8_run_rom instead.
The window is too small
Raise the scale: --scale 20. The default is 12.
Questions
Where do I get ROMs?
None are bundled. tests/roms/fetch_roms.sh downloads the free Timendus test ROMs. For games, use homebrew and public-domain programs their authors have released, or write your own.
Does chip8 run SUPER-CHIP or XO-CHIP games?
No. High resolution, scrolling and colour planes are out of scope.
Can I change the colours or save my game?
No. Custom palettes and save states are not included.
Can I remap the keys?
No. The keypad is fixed to the 1234 / QWER / ASDF / ZXCV block.
Where do I report a problem?
Open an issue on the chip8 issues page.