termin-8 0.1.6

CHIP-8 emulator that runs in your terminal
termin-8-0.1.6 is not a library.

Termin-8

crates.io dependency status

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

Powered by deca, it supports CHIP-8, SUPER-CHIP (SCHIP) and XO-CHIP programs.

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:

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.