# Chip-8 cabinet

## Interpreter

The Chip-8 / SUPER-CHIP interpreter behind `/play/chip8` is original code written for this site
(`lib/chip8/cpu.ts`, `lib/chip8/runtime.ts`). It is not derived from any other emulator.

- Full Chip-8 instruction set, plus SUPER-CHIP: 128x64 hires (`00FE`/`00FF`), scrolling (`00CN`, `00FB`, `00FC`),
  16x16 sprites (`DXY0`), big font (`FX30`), flag registers (`FX75`/`FX85`) and exit (`00FD`).
- 60 Hz delay and sound timers; the sound timer drives a WebAudio square-wave beep.
- Cycles per frame set per ROM (the archive's Octo `tickrate`).
- The random number opcode (`CXNN`) uses a seeded generator, so a run is fully determined by its ROM, seed and
  key presses. That is what makes "Replay last run" and the ghost of your last run possible.

### Quirks

Quirk flags follow Octo, which the archive ROMs were tested with. Defaults are Octo's (all off):

| Flag        | Off (default)                    | On                          |
|-------------|----------------------------------|-----------------------------|
| `shift`     | `8XY6`/`8XYE` shift VY into VX   | shift VX in place           |
| `loadStore` | `FX55`/`FX65` advance I by X+1   | leave I unchanged           |
| `jump`      | `BNNN` jumps to NNN + V0         | `BXNN` jumps to XNN + VX    |
| `logic`     | `8XY1/2/3` leave VF alone        | reset VF to 0               |
| `clip`      | sprites wrap at the edges        | sprites clip at the edges   |
| `vblank`    | draws run at full speed          | a draw ends the frame       |

Per-ROM settings live in `roms.json`. Only two ROMs here change them: Dino Run (`clip`, `vblank`, `logic`) and
Super Octogon (`shift`, `loadStore`, `jump`, `clip`). The stack is allowed to grow past 16 levels, as in Octo,
because Super Square leaks a few frames each time it restarts.

## ROMs

Every ROM here comes from the [Chip8 Community Archive](https://github.com/JohnEarnest/chip8Archive) curated by
John Earnest. The archive places everything in it under
[Creative Commons 0](https://creativecommons.org/publicdomain/zero/1.0/) ("No Rights Reserved"); authors who
submit to it agree to that licence. Titles, authors and settings come from the archive's `programs.json`.

| ROM              | Author(s)                              | Made for   | Platform  | Licence |
|------------------|----------------------------------------|------------|-----------|---------|
| Br8kout          | SharpenedSpoon                         | Octojam 1  | Chip-8    | CC0     |
| Super Pong       | offstatic                              | Octojam 8  | Chip-8    | CC0     |
| Outlaw           | John Earnest                           |            | Chip-8    | CC0     |
| Spacejam!        | William Donnelly                       | Octojam 2  | Chip-8    | CC0     |
| Snek             | John Earnest                           | Octojam 8  | Chip-8    | CC0     |
| Glitch Ghost     | Jackie Kircher                         | Octojam 1  | Chip-8    | CC0     |
| Piper            | Aeris, Jordan Mecom, Lillian Wang      | Global Game Jam 2017 | Chip-8 | CC0 |
| Dino Run         | Andrezinrc                             |            | Chip-8    | CC0     |
| Eaty the Alien   | John Earnest                           | Octojam 2  | SUPER-CHIP | CC0    |
| Sw8 Copter       | John Earnest                           |            | SUPER-CHIP | CC0    |
| Super Square     | tann                                   | Octojam 1  | SUPER-CHIP | CC0    |
| Super Octogon    | John Earnest                           | Octojam 8  | SUPER-CHIP | CC0    |

## Controls

The 16-key pad is on 1234 / QWER / ASDF / ZXCV. Each ROM also binds the arrow keys and Space to the keys it
uses, and a gamepad's d-pad and A/B buttons follow the same bindings. On touch screens only the buttons the
selected ROM uses are shown.

## Replays

Your last run on each ROM (seed plus key changes, never anything else) is kept in this browser's
`localStorage` under `arcade:chip8:last-v1`. Nothing is sent anywhere.