/chip-8

CHIP-8 Interpreter

Primary LanguageGoMIT LicenseMIT

CHIP-8

A Go implementation of a CHIP-8 interpreter.

Run with a standalone window: standard version

Or as a TUI:

tui version

See more demos here.

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:

  1. Setting the appropriate Environment Variable.
  2. 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

You might also want to set throttle_speed to 60 if you're setting all these values for older games.

Theme

You can tweak the off and on color by

Resources

When things got quirky:

ROMs:

Demos

pong

octojam

october