termin-8 0.1.5

CHIP-8 emulator that runs in your terminal
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

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)

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

It uses [`deca`](https://crates.io/crates/deca) as the emulator backend, which supports CHIP-8, SUPER-CHIP (SCHIP) and XO-CHIP programs.

## 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 also use some other keys:

* <kbd>i</kbd>: interrupt execution, or continue execution after interrupt
* <kbd>o</kbd>: single-step (while interrupted)
* <kbd>Esc</kbd>: exit

## 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:

<table>
<tr>
<th>CHIP-8 resolution</td>
<th>Unicode version</td>
<th>Minimum terminal size</td>
<th>Pixel size</td>
<th>XO-CHIP colors</td>
</tr>

<tr>
<td rowspan="4">64x32 (lores)<br>CHIP-8, SCHIP, XO-CHIP</td>
<td rowspan="3">1.0.0</td>
<td>128x32</td>
<td>██</td>
<td>✔</td>
</tr>

<tr>
<td>64x32</td>
<td>█</td>
<td>✔</td>
</tr>

<tr>
<td>64x16</td>
<td>▀</td>
<td>✔</td>
</tr>

<tr>
<td>3.2</td>
<td>32x16</td>
<td>▘</td>
<td>❌</td>
</tr>

<tr>
<td rowspan="4">128x64 (hires)<br>SCHIP, XO-CHIP</td>
<td rowspan="3">1.0.0</td>
<td>256x64</td>
<td>██</td>
<td>✔</td>
</tr>

<tr>
<td>128x64</td>
<td>█</td>
<td>✔</td>
</tr>

<tr>
<td>128x32</td>
<td>▀</td>
<td>✔</td>
</tr>

<tr>
<td>3.2</td>
<td>64x32</td>
<td>▘</td>
<td>❌</td>
</tr>

</table>

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.2 is much less common. Font families like _DejaVu_ and _Fira Code_ 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).