A Go implementation of a CHIP-8 interpreter.
Run with a standalone window:
Or as a TUI:
See more demos here.
Download the latest release for your platform.
Launch with your ROM:
chip8 <chip-8 file>
Log instructions as they are processed (Warning! produces lots of messages):
chip8 -debug <chip-8 file>
While the program passes all test ROMs from Timendus' Test Suite, YMMV with random ROMs you pull from the Internet.
Here's the full usage:
Run CHIP-8 programs from the CLI with ease
Usage:
chip8 <rom> [flags]
chip8 [command]
Available Commands:
help Help about any command
tui Run in TUI mode
Flags:
-c, --cosmac Run in COSMAC VIP mode
-d, --debug Show debug messages
-h, --help help for chip8
--list-modes Show supported CHIP-8 variants
--write-config Write current config to default location. Existing config file will be overwritten!
Use "chip8 [command] --help" for more information about a command.
Various aspects of the interpreter can be tweaked in these ways, listed by precedence:
- Setting the appropriate Environment Variable.
- Creating a
config.tomlfile in the same directory thatchip8is being executed from
Running chip8 --write-config will (over)write all configuration options to a config.toml.
This table summarizes the existing configuration values and how to set them.
| Configuration | Default | TOML | Environment |
|---|---|---|---|
| Change the display scale factor. 1 uses the original 64x32 pixel display. |
10 | display_scale_factor |
CHIP8_DISPLAY_SCALE_FACTOR |
| Delay the rate the interpreter processes instructions 60 gives an execution rate of 60 Hz |
0 | throttle_speed |
CHIP8_THROTTLE_SPEED |
| Stop execution after this many instructions are executed | 0 | cycle_limit |
CHIP8_CYCLE_LIMIT |
| Set the color used for Off pixels | "Iris" | off_color |
CHIP8_OFF_COLOR |
| Set the color used for On pixels | "Pine" | off_color |
CHIP8_OFF_COLOR |
The colors can be chosen from the Rose Pine palette.
Timendus provides this succinct description of what Quirks are:
CHIP-8, SUPER-CHIP and XO-CHIP have subtle differences in the way they interpret the bytecode. We often call these differences quirks...This is one of the hardest parts to "get right" and often a reason why "some games work, but some don't".
All quirks belong to some other variation of CHIP-8. They can be set individually in config.toml. To use the different generations of CHIP-8, run with the appropriate flag set. This is equivalent to enabling all the quirks for that chipset:
# Enable all COSMAC VIP quirks
chip8 --cosmac <ROM>
The following quirks are grouped under cosmac-vip section in the configuration file.
| Configuration Value | Description |
|---|---|
reset_vf |
The AND, OR and XOR opcodes (8xy1, 8xy2, and 8xy3) reset the flags register (VF) to zero |
increment_i |
Increment the memory index while Fx55 and Fx56 operate |
You might also want to set throttle_speed to 60 if you're setting all these values for older games.
You can tweak the off and on color by
- Introduction to the building blocks needed to write an interpreter for CHIP-8: realemulator101's Introduction to CHIP-8
- How to write the whole thing, but hints only. I used this the most ✨: Tobias' Guide to making a CHIP-8 emulator
- Quick instruction reference: mattmikolay's CHIP‐8-Instruction-Set
- More detailed reference: Cowgod's Chip-8 Technical Reference
- Test ROMs! Could not have built this without them ✨: Timendus' CHIP-8 test suite
When things got quirky:
ROMs:
