Termin-8

CHIP-8 emulator that runs in your terminal and is Octo compliant.

It will also auto-resize its display to fit your terminal (at the cost of widespread font support and XO-CHIP color in the smallest sizes).

Installation

First, install Rust. Then, in your terminal:

cargo install termin-8

Usage

Termin-8 should work on Windows, Linux, and macOS. If it doesn't, please file an issue.

Download CHIP-8 ROMs from the internet, like the Chip8 Community Archive, or make your own in Octo.

Then run Termin-8 in your terminal:

termin-8 ROM

There are some command line options:

termin-8 --help

The hexadecimal CHIP-8 keypad is customarily mapped to the following keyboard keys:


1	2	3	4
q	w	e	r
a	s	d	f
z	x	c	v

In addition, the arrow keys are bound to WASD.

You can press Esc to exit.

Debugging capabilities

Termin-8 can be used for testing while developing CHIP-8 games, as an alternative to Octo (web) and C-Octo (SDL).

However, Termin-8 can't yet compile Octo code on its own. In an all-terminal workflow, use C-Octo's octo-cli tool to compile your code. octo-cli can output a symbol file alongside the CHIP-8 binary if you use the -s command line option, and -s is likewise supported by Termin-8 for reading such a symbol file.

If a symbol file containing breakpoints is loaded, hitting those breakpoints will interrupt execution and display the contents of all registers.

Press the following keys while Termin-8 is running for further debugging:

i: interrupt execution and display contents of registers (or continue execution after interrupt)
o: single-step (while interrupted)
u: step out (execute until the current subroutine returns)
l: step over (execute the contents of any subroutines until they return to the current level)
m: toggle monitors (if a symbol file containing monitors has been loaded)

Terminal requirements

Note that the terminal requirements vary depending on what kind of program you attempt to run.

Here's a table with the required terminal size and Unicode support needed to get features such as XO-CHIP color support, depending on the resolution of the CHIP-8 program you're running and the Unicode Block Elements support of your font:

CHIP-8 resolution	Unicode version	Minimum terminal size	Pixel size	XO-CHIP colors
64x32 (lores) CHIP-8, SCHIP, XO-CHIP	1.0.0	128x32	██	✔
		64x32	█	✔
		64x16	▀	✔
	3.2	32x16	▘	❌
128x64 (hires) SCHIP, XO-CHIP	1.0.0	256x64	██	✔
		128x64	█	✔
		128x32	▀	✔
	3.2	64x32	▘	❌

CHIP-8 resolution	Unicode version	Minimum terminal size	Pixel size	XO-CHIP colors
64x32 (lores) CHIP-8, SCHIP, XO-CHIP	1.0.0	128x32	██	✔
		64x32	█	✔
		64x16	▀	✔
	3.2	32x16	▘	❌
	3.0	32x8	⠁	❌
128x64 (hires) SCHIP, XO-CHIP	1.0.0	256x64	██	✔
		128x64	█	✔
		128x32	▀	✔
	3.2	64x32	▘	❌
	3.0	64x16	⠁	❌

Notes:

In your browser, the smallest pixel block (▘) probably looks square, but this might not be the case with your monospace terminal font.
Pretty much all fonts support the basic Unicode Block Elements in Unicode 1.0.0 which are used for the larger pixel blocks (█, ▀ and ▄), but support for the smallest blocks (like ▘) from Unicode 3.0 and 3.2 is much less common. Font families like DejaVu and Fira Code support them.
The smallest pixel blocks (like ⠁) are Unicode Braille symbols, which aren't as common. Patched Nerd Fonts support them.

Limitations

Some games might not detect keypresses correctly. This is because detecting when a key is released is very hard in a terminal. Termin-8 does an approximation of keypress duration, but your OS's "key repeat" settings will influence how often it can poll for key presses.
Your terminal's bell will sound when there's sound, but XO-CHIP music is not supported (as a terminal can't play sound on its own).

Configuration file

Termin-8 will look for a file named .octo.rc in the user's home directory, which can be used to configure some useful settings. This file is also used by C-Octo.

You can also supply a configuration file with the -c command line option. This can be useful for setting some options for specific games – colors, to match the author's artistic vision, or "quirky" behavior, to make the game run correctly.

The file has a traditional .INI structure – empty lines or lines beginning with # are ignored, and anything else consists of a key and value separated by =. Meaningful keys are as follows:

core.tickrate: number of CHIP-8 instructions to execute per 60hz frame.
core.max_rom: the maximum number of bytes the compiler will permit when assembling a ROM.
core.font: one of {octo, vip, dream_6800, eti_660, schip, fish} to select the built-in CHIP-8 font.
color.plane0, color.plane1, color.plane2, color.plane3: colors for the 4 XO-CHIP "plane" colors.
color.background: the border drawn behind the CHIP-8 display when no sound is being played.
color.sound: the alternate border color when sound is being played.
quirks.shift: if 1, vx <<= vy and vx >>= vy modify vx in place and ignore vy, like SCHIP.
quirks.loadstore: if 1, load and store do not post-increment i, like SCHIP.
quirks.jump0: if 1, emulate a buggy behavior of SCHIP on the HP-48: the 4 high bits of the target address of jump0 determines the offset register used (instead of always v0).
quirks.logic: if 1, clear vf after &=,|= and ^=. On the VIP, these instructions leave vf in an unknown state.
quirks.clip: if 1, do not "wrap" sprite drawing around the edges of the display.
quirks.vblank: if 1, drawing a sprite will block until the end of the 60hz frame, like the VIP.

All colors are specified as 6-digit RGB in hexadecimal, like 996600. The default quirks settings, palette, and other options correspond to those of web-octo.

tobiasvl / termin-8