chip8

Go CHIP-8

This is (yet another) CHIP-8 and Super CHIP-8 emulator written in Go. Yes there are many others but this one is mine.

What is CHIP-8? It’s a simple 8-bit virtual machine developed in the 1970s, which found new life in the 90s on HP graphing calculators. It’s become the defacto “hello world” for emulator developers to get started with.

https://en.wikipedia.org/wiki/CHIP-8

Screenshots

Goals:

Features:

Supporting technologies and libraries:

Status

Getting Started

Try web version

Online WASM version is playable here with a set of roms/programs provided

https://code.benco.io/chip8/web/

Installing & Running

Download from releases, unzip/untar and run :)

chip8 <flags> <program-filename>

  -bg int
        Colour of background, pallette index: 0-8 (default 0)
  -fg int
        Colour of foreground pixels, pallette index: 0-8 (default 2)
  -nocolour
        Force mono mode even if a colour map file is found
  -pallette string
        Colour pallette; spectrum, c64 or vaporwave (default "spectrum")
  -scale int
        Size of pixels, default results in a 640x320 window (default 10)
  -speed int
        Speed of the emulator in cycles per tick (default 12)
  -debug int
        0 = off, 1 = sprites only, 2 = full

Controls

The keys on the left hand side of the keyboard are mapped to the 16 keys of the CHIP-8 “keypad” as follows:

In addition the emulator provides several other keys

Colour Support

This emulator supports two main colour modes, both modes have 9 colours (black and 8 other colours) and comes with three builtin colour pallettes:

The pallettes are all indexed the same:

  1. Black
  2. White
  3. Red
  4. Green
  5. Blue
  6. Magenta / Pink
  7. Yellow
  8. Cyan / Light Blue
  9. Orange

Mode: 1-Bit Monochrome

This is the default mode, in this mode you can specify the foreground colour (for pixels set to 1) and background colour (for pixels that are 0), the colours are specified as a value between 0 and 8 for the pallette index. Defualts are 0 (black) for background and 2 (green) for foreground

Mode: Multi-Colour Mapping

This is a special mode, unique (AFAIK) to this emulator and it attempts to add multi-colour support to the CHIP-8 system without the need for any software or system changes (i.e. it can work with ALL existing ROMs, games and programs), and supports with both CHIP-8 and Super CHIP-8 software

This mode is only enabled if a colour mapping file is found.
Colour mapping files are YAML files named as follows {rom-name}.colours.yaml and should be in the same directory as the ROM file, e.g. of you were loading the following program ROM roms/stuff/foo.ch8, the mapping file looked for would be roms/stuff/foo.ch8.colours.yaml

If this file is not found this mode is disabled and the emulator defaults back to 1-bit mode.

In summary this mode relies on mapping sprite addresses in memory with colour (pallette index) values. e.g. if the program stored the sprite for an enemy space ship at address 0xA40 we could decide to draw that sprite in green, but the sprite stored at 0xA58 could be shown in red.

The mapping file syntax is a little complex but a summary and example follows:

background: 0 # black background
default: 3 # make foreground color green
sprites:
  '0AF8': 2 # sprite we want in red
  '0A68': 4 # sprite we want in blue
  '0A88': 4 # sprite we want in blue
ranges:
  - colour: 6 # a range of sprites in yellow
    start: '0B18'
    end: '0B30'
  - colour: 1 # a range of sprites in white
    start: '0B5C'
    end: '0BBC'

In order to aid creation of these files a special debug mode -debug=1 is included, which will output the addresses of sprites the first time they are drawn.

TODO: Full explanation / reference for .colours.yaml files

Check out the roms directory in this repo for some example colour mapping files

Developing & building locally

$ make
build                🔨 Run a local build
help                 💬 This help message :)
lint-fix             📝 Lint & format, will try to fix errors and modify code
lint                 🔍 Lint & format, will not fix but sets exit code on error
run                  🏃‍ Run application, used for local development
test                 🤡 Run those unit tests and pretend you have no bugs

Building (Linux)

Install pre-reqs:

Then simply run make build, the executable binaries are output to ./bin/ the WASM version is placed into ./web/

Note. Even when building under Linux, the Windows version will be built too

Repository Structure

A brief description of the top-level directories of this project are:

/cmd        - Main apps, both standalone and WASM versions
/docs       - Docs, not much here
/pkg        - Go packages and modules, most of the code is here
/roms       - A handful of CHIP8 ROMs and programs for testing
/web        - Web / WASM version

Known Issues

Acknowledgements & Links

I used the following links (among others) when writing this emulator

This site is open source. Improve this page.