CHIP-8 is a fantasy video game console definition from the 1970s by Joseph Weisbecker.
This is an interpreter for running CHIP-8 programs on Apple II models that support Double Low Resolution graphics (DGR):
- Apple IIe* (original), with 80 column card
- Apple IIe Enhanced*, with 80 column card
- Apple IIc
- Apple IIc Plus
- Apple IIgs
- Macintosh IIe Option Card (untested)
- Clones such as the Laser 128, Franklin ACE 2200, Franklin ACE 500
- Emulators such as MAME, Virtual ][, AppleWin, etc.
* The rare Apple IIe Revision A motherboard does not support double-resolution graphics.
It runs in ProDOS-8 and follows the "interpreter protocol" so that launchers such as Bitsy Bye and Apple II DeskTop can automatically launch CHIP-8 programs with it.
💾 The disk image includes several example CHIP-8 programs including demos and games. Download the latest disk image and run it in your favorite emulator:
https://github.com/a2stuff/chip8.system/releases/latest/download/chip8.po
🖥️ Try it right in your browser with Apple2TS.
To run a CHIP-8 program, copy the file to a ProDOS-8 2.4 disk with the CHIP8.SYSTEM renamed to (or duplicated as) BASIS.SYSTEM in the root directory, then boot the disk. Bitsy Bye will run and show a list of files and directories. Pick the CHIP-8 file and it will launch automatically.
TIP: Apple II DeskTop will also use a copy of
BASIS.SYSTEMin the same directory to launch unknown file types.
There are many online archives of CHIP-8 programs:
- https://johnearnest.github.io/chip8Archive/?sort=platform#chip8
- https://chip-8.github.io/links/
- https://github.com/kripod/chip8-roms
- https://www.zophar.net/pdroms/chip8/chip-8-games-pack.html
NOTE: Only CHIP-8 programs are supported, not SUPER-CHIP or XO-CHIP.
Press Esc at any time to quit to ProDOS.
Press Del at any time to restart the program.
The CHIP-8 assumes a 16-key keypad like the COSMAC VIP:
| 1 | 2 | 3 | C |
| 4 | 5 | 6 | D |
| 7 | 8 | 9 | E |
| A | 0 | B | F |
Use these keys on a QWERTY keyboard instead:
| 1 | 2 | 3 | 4 |
| Q | W | E | R |
| A | S | D | F |
| Z | X | C | V |
For example, the BLINKY game (a Pac-Man clone) uses keypad keys 7 and 8 for left and right, and 3 and 6 for up and down, so on the Apple II keyboard you would use A and S for left and right, and 3 and E for up and down.
TIP: CHIP-8 programs use a variety of key combinations, often very strange ones. Look for documentation where you found the program, or mash the keys to figure out the controls. Good luck!
Other controls:
- Press 9 and 0 to change border colors.
- Press [ and ] to change background colors.
- Press , and . to change foreground colors.
Some CHIP-8 programs require different compatibility settings, called "quirks".
| Quirk Name | ID | Default | Key | Bit |
|---|---|---|---|---|
| VF Reset | logic |
on / true | ! | 0 |
| Memory | memoryLeaveIUnchanged* |
on / false | @ | 1 |
| Display Wait | vblank |
on / true | # | 2 |
| Clipping | wrap* |
on / false | $ | 3 |
| Shifting | shift |
off / false | % | 4 |
| Jumping | jump |
off / false | ^ | 5 |
Quirk names are per Timendus's CHIP-8 quirks test. The defaults for CHIP8.SYSTEM match the passing expectations in these tests.
IDs are per the CHIP-8 database, which lists the same quirks but with slightly different expectations. A * signifies that sense is inverted, i.e. turning the quirk on, per the test definition, is the same as the false setting in the database definition.
Defaults "on" and "off" reference Timendus' tests, "true" and "false" reference the CHIP-8 database.
To toggle a quirk on or off at runtime, press the Key. The CHIP-8 program will restart with the new setting.
It is possible to persistently configure the quirks for a CHIP-8 program. This is done by changing the ProDOS file type of the program to $5D (a.k.a. ENT or Entertainment), and setting the aux type to $C800 (for "CHIP-8") with the lower byte used as "quirks" flags, per the Bit column.
For example, the BLINKY game (a Pac-Man clone) requires the "Memory" quirk disabled (bit 1) and the "Shifting" quirk enabled (bit 4), so is packaged with file type $5D and aux type $C81D, since $1D is binary 00011101 meaning bit 0 is on, bit 1 is off, bit 2 is on, bit 3 is on, bit 4 is on, and bit 5 is off.
If the file type is not $5D or the aux type does not start with $C8 then programs start with all quirks set to the defaults. This is equivalent to file type $5D and aux type $C80F, since $0F is binary 00001111 meaning bits 0-3 are on and bits 4-5 are off.
For detailed "quirks" definitions, see https://github.com/Timendus/chip8-test-suite?tab=readme-ov-file#the-test
TIP: You can use Apple II DeskTop to easily change the file type and auxtype; use the Change Type accessory in the Apple menu.
- https://tobiasvl.github.io/blog/write-a-chip-8-emulator/
- https://github.com/Timendus/chip8-test-suite
- https://chip-8.github.io/
Fetch, build, and install cc65 (in a separate directory):
git clone https://github.com/cc65/cc65
make -C cc65 && make -C cc65 avail
Then run: make
To produce a ProDOS disk image, first install and build Cadius (in a separate directory):
git clone https://github.com/mach-kernel/cadius
make -C cadius && make -C cadius install
Then run: make package