Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tobiasvl/termin-8

Octo-compliant CHIP-8 emulator frontend that runs in your terminal
https://github.com/tobiasvl/termin-8

chip-8 chip-8-debugger chip-8-emulator chip-8-interpreter chip8 chip8-emulator chip8-interpreter

Last synced: 17 days ago
JSON representation

Octo-compliant CHIP-8 emulator frontend that runs in your terminal

Awesome Lists containing this project

README 

        
Termin-8

========

[![crates.io](https://img.shields.io/crates/v/termin-8.svg)](https://crates.io/crates/termin-8)

[![dependency status](https://deps.rs/repo/github/tobiasvl/termin-8/status.svg)](https://deps.rs/crate/termin-8)



CHIP-8 emulator that runs in your terminal and is [Octo](https://github.com/JohnEarnest/Octo) compliant.



Powered by [`deca`](https://crates.io/crates/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](https://www.rust-lang.org/tools/install). Then, in your terminal:



```sh

cargo install termin-8

```



## Usage



Termin-8 should work on Windows, Linux, and macOS. If it doesn't, please [file an issue](https://github.com/tobiasvl/termin-8/issues/new/choose).



Download CHIP-8 ROMs from the internet, like the [Chip8 Community Archive](https://github.com/JohnEarnest/chip8Archive/), or make your own in [Octo](https://github.com/JohnEarnest/Octo).



Then run Termin-8 in your terminal:



```sh

termin-8 ROM

```



There are some command line options:



```sh

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](https://JohnEarnest.github.io/Octo) (web) and [C-Octo](https://github.com/JohnEarnest/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`](https://github.com/JohnEarnest/c-octo#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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/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](https://www.nerdfonts.com/) 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](https://blog.robertelder.org/detect-keyup-event-linux-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](https://github.com/JohnEarnest/c-octo#configuration-file).



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.