CHIP-8 emulator with debug view and integrated assembler. Written in C++ using SDL2.
- Execute ROM files
- Assemble and execute Assembly files
- Increase/Decrease emulation speed
- Pause/Unpause
- Create screenshot
- Reset
- Single-step mode
- Debug mode (shows the registers, opcode and stack)
- Fullscreen mode
- Memory, register and stack dump
Dependencies:
- SDL2
- SDL2_ttf
After cloning the repository, execute git submodule init to fetch the assembler's source code.
On a Debian-based system they can be installed by running the command:
sudo apt install libsdl2-dev libsdl2-ttf-dev
Compiling:
mdir build # Create a directory for the build files
cd build # Step into the directory
cmake .. # Generate build files
make # BuildInstall WSL2 and follow the Linux building instructions.
TODO: Test if they work on WSL2
When you start the emulator, the ROM selector opens. It shows the ROMs (.ch8) and Assembly (.asm) files in the ./roms, ../submodules/chip8asm/tests and the current directories (recursively). You can copy games to these folders.
When you selected the ROM or assembly using the arrow keys, press Enter.
You can cancel the selection by pressing the Escape key.
You can also call the emulator with the ROM/Assembly file as parameter. Example:
./chip8emu ./my_fav_game.ch8You can write games using Chip8asm's syntax. They are assembled after loading.
After you select the ROM, the emulator window opens. There you can see the frame buffer.
The title contains the string CHIP-8 and the speed of the emulation.
If the program is waiting for input, it is indicated as waiting for keypress
If the user paused the program, there is [PAUSED] at the end of the title.
The window displays the output of the executed ROM. The programs can draw on a 64px by 32px buffer. The coordinates are scaled up (using hardware-accelerated texture scaling) so the output fills the window with fixed ratio.
The content can flicker, this is due to how the CHIP-8 interpreter is designed.
The CHIP-8 can accept 16 (0xf) keys by design.
The original keypad:
1 2 3 c
4 5 6 d
7 8 9 e
a 0 b f
This is how the keys are mapped to the (US) keyboard:
1 2 3 4
q w e r
a s d f
z x c v
The function keys can be modified in the config.h file before compiling.
Pauses the program. Press again to resume. Disables stepping mode if it is active.
Toggles the help screen. The help screen shows the keybindings and some compilation info.
Creates a screenshot of the game and saves it as a BMP image. The filename is the time in the C strftime() format %y%m%d%H%M%S.bmp.
Resets the emulator. All the registers, the stack, the memory and the frame buffer are reset to the default values, then the ROM is loaded in again.
Enables stepping mode. Disables paused mode if active.
Executes an instruction in stepping mode. No effect if stepping mode is not active.
Slows down the emulation speed by 5%.
Speeds up the emulation speed by 5%.
Hides/Shows the mouse cursor.
Enables debug mode.
In debug mode you can see the currently executed opcode, the program counter, the index register, the stack pointer, the content of the stack, the register values, the delay and the sound timers. If the program reads from a register, its background is green colored, if the program writes to it, it is red colored, if both, its yellow. It is also displayed when a program reads which key is pressed.
All the values are displayed as hexadecimal with the 0x prefix.
Toggles the fullscreen mode.
Exits the emulator.
Dumps the memory, the registers, the framebuffer and the stack to the terminal.
Toggle compatibility option:
Set register X to register Y shifted instead of X in case of shift opcodes.
Space invaders is known to only work with this option set to False.
Defaults to True.
Toggle compatibility option:
Increment I register after register load/save in case of FX55 and FX66 opcodes.
Defaults to True.
Licensed under the MIT license.