CHIP-8

A Go implementation of a CHIP-8 interpreter.

Run with a standalone window:

Or as a TUI:

Installation

Download the latest release for your platform.

Usage

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.

Configuration

Various aspects of the interpreter can be tweaked in these ways, listed by precedence:

Setting the appropriate Environment Variable.
Creating a config.toml file in the same directory that chip8 is 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.

Run Modes and Quirks

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>

COSMAC VIP

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