- What is it?
- License
- Compiling
- Running
- Customization
- ROM Compatibility
- Third Party Licenses and Attributions
This project is a Chip 8 emulator written in Java. There are two other versions of the emulator written in different languages:
The original goal of these projects was to learn how to code a simple emulator.
In addition to supporting Chip 8 ROMs, the emulator also supports the Super Chip 8 instruction set. Note that no additional configuration is needed to run a Super Chip 8 ROM - simply run the ROM the same way you would run a normal Chip 8 ROM.
This project makes use of an MIT license. Please see the file called
LICENSE for more information. Note that this project may make use of other
software that has separate license terms. See the section called Third Party Licenses and Attributions below for more information on those
software components.
To compile the project, you will need a Java Development Kit (JDK) version 8 or greater installed. Recently, Oracle has changed their license agreement to make personal and developmental use of their JDK free. However, some other use cases may require a paid subscription. Oracle's version of the JDK can be downloaded here. Alternatively, if you prefer to use a JRE with an open-source license (GPL v2 with Classpath Exception), you may visit https://adoptopenjdk.net and install the latest Java Development Kit (JDK) for your system. Again, JDK version 8 or better will work correctly.
To build the project, switch to the root of the source directory, and type:
./gradlew build
On Windows, switch to the root of the source directory, and type:
gradlew.bat build
The compiled JAR file will be placed in the build/libs directory, as a file called
emulator-1.0.1-all.jar.
You will need a copy of the Java Runtime Environment (JRE) version 8 or greater installed in order to run the compiled JAR file. For most systems, you can install Java 8 JRE by visiting http://java.com and installing the Oracle Java Runtime Environment for your platform. This version of the JRE is free for personal use but contains a custom binary license from Oracle. Alternatively, if you prefer to use a JRE with an open-source license (GPL v2 with Classpath Exception), you may visit https://adoptopenjdk.net and install the latest Java Development Kit (JDK) for your system, which will include an appropriate JRE.
By default, the emulator can start up without a ROM loaded. Simply double click the JAR file, or run it with the following command line:
java -jar emulator-1.0.1-all.jar
The command-line interface currently requires a single argument, which is the full path to a Chip 8 ROM:
java -jar emulator-1.0.1-all.jar /path/to/rom/filename
This will start the emulator with the specified ROM.
The --scale switch will scale the size of the window (the original size
at 1x scale is 64 x 32):
java -jar emulator-1.0.1-all.jar /path/to/rom/filename --scale 10
The command above will scale the window so that it is 10 times the normal size.
You may also wish to experiment with the --delay switch, which instructs
the emulator to add a delay to every operation that is executed. For example,
java -jar emulator-1.0.1-all.jar /path/to/rom/filename --delay 10
The command above will add a 10 ms delay to every opcode that is executed. This is useful for very fast computers (note that it is difficult to find information regarding opcode execution times, as such, I have not attempted any fancy timing mechanisms to ensure that instructions are executed in a set amount of time).
Over time, various extensions to the Chip8 mnemonics were developed, which resulted in an interesting fragmentation of the Chip8 language specification. As discussed in Octo's Mastering SuperChip documentation, one version of the SuperChip instruction set subtly changed the meaning of a few instructions from their original Chip8 definitions. This change went mostly unnoticed for many implementations of the Chip8 language. Problems arose when people started writing programs using the updated language model - programs written for "pure" Chip8 ceased to function correctly on emulators making use of the altered specification.
To address this issue, Octo implements
a number of quirks modes so that all Chip8 software can run correctly,
regardless of which specification was used when developing the Chip8 program.
This same approach is used here, such that there are several quirks flags
that can be passed to the emulator at startup to force it to run with
adjustments to the language specification.
Additional quirks and their impacts on the running Chip8 interpreter are examined in great depth at Chromatophore's HP48-Superchip repository. Many thanks for this detailed explanation of various quirks found in the wild!
The --shift_quirks flag will change the way that register shift operations work.
In the original language specification two registers were required: the
destination register x, and the source register y. The source register y
value was shifted one bit left or right, and stored in x. For example,
shift left was defined as:
Vx = Vy << 1
However, with the updated language specification, the source and destination
register are assumed to always be the same, thus the y register is ignored and
instead the value is sourced from x as such:
Vx = Vx << 1
The original specification of the Chip8 language defined a 4K memory size
for the interpreter. The addition of the XO Chip extensions require a 64K
memory size for the interpreter. By default, the interpreter will start w
ith a 64K memory size, but this behavior can be controlled with the
--mem_size_4k flag, which will start the emulator with 4K.
The original Chip8 language specification called for pixels to be turned
on or off. It did not specify what color the pixel states had to be. The
emulator lets the user specify what colors they want to use when the emulator
is running. Color values are specified by using HTML hex values such as
AABBCC without the leading #. There are currently 4 color values that can
be set:
--color_0specifies the background color. This defaults to000000.--color_1specifies bitplane 1 color. This defaults toFF33CC.--color_2specifies bitplane 2 color. This defaults to33CCFF.--color_3specifies bitplane 1 and 2 overlap color. This defaults toFFFFFF.
For Chip8 and SuperChip 8 programs, only the background color color_0
(for pixels turned off) and the bitplane 1 color color_1 (for pixels turned
on) are used. Only XO Chip programs will use color_2 and color_3 when
the additional bitplanes are potentially used.
The file components/Keyboard.java contains several variables that can be
changed to customize the operation of the emulator. The Chip 8 has 16 keys:
The original Chip 8 had a keypad with the numbered keys 0 - 9 and A - F (16 keys in total). The original key configuration was as follows:
1 |
2 |
3 |
C |
|---|---|---|---|
4 |
5 |
6 |
D |
7 |
8 |
9 |
E |
A |
0 |
B |
F |
The Chip8Java emulator maps them to the following keyboard keys by default:
1 |
2 |
3 |
4 |
|---|---|---|---|
Q |
W |
E |
R |
A |
S |
D |
F |
Z |
X |
C |
V |
Pressing a debug key at any time will cause the emulator to enter into a different mode of operation. The debug keys are:
| Keyboard Key | Effect |
|---|---|
ESC |
Quits the emulator |
Here are the list of public domain ROMs and their current status with the emulator, along with links to public domain repositories where applicable.
| ROM Name | Working | Flags |
|---|---|---|
| 1D Cellular Automata | ✔️ | |
| 8CE Attourny - Disc 1 | ✔️ | |
| 8CE Attourny - Disc 2 | ❓ | |
| 8CE Attourny - Disc 3 | ❓ | |
| Bad Kaiju Ju | ✔️ | |
| Br8kout | ✔️ | |
| Carbon8 | ✔️ | |
| Cave Explorer | ✔️ | |
| Chipquarium | ✔️ | |
| Danm8ku | ❌ | |
| down8 | ✔️ | |
| Falling Ghosts | ❓ | |
| Flight Runner | ❓ | |
| Fuse | ❓ | |
| Ghost Escape | ❓ | |
| Glitch Ghost | ❓ | |
| Horse World Online | ❓ | |
| Invisible Man | ❓ | clip_quirks |
| Knumber Knower | ❓ | |
| Masquer8 | ❓ | |
| Mastermind | ❓ | |
| Mini Lights Out | ❓ | |
| Octo: a Chip 8 Story | ❓ | |
| Octogon Trail | ❓ | |
| Octojam 1 Title | ❓ | |
| Octojam 2 Title | ❓ | |
| Octojam 3 Title | ❓ | |
| Octojam 4 Title | ❓ | |
| Octojam 5 Title | ❓ | |
| Octojam 6 Title | ❓ | |
| Octojam 7 Title | ❓ | |
| Octojam 8 Title | ❓ | |
| Octojam 9 Title | ❓ | |
| Octojam 10 Title | ❓ | |
| Octo Rancher | ❓ | |
| Outlaw | ❓ | |
| Pet Dog | ❓ | |
| Piper | ❓ | |
| Pumpkin "Dress" Up | ❓ | |
| RPS | ❓ | |
| Slippery Slope | ❓ | |
| Snek | ❓ | |
| Space Jam | ❓ | |
| Spock Paper Scissors | ❓ | |
| Super Pong | ❓ | |
| Tank! | ❓ | |
| TOMB STON TIPP | ❓ | |
| WDL | ❓ |
| ROM Name | Working | Flags |
|---|---|---|
| Applejak | ❓ | |
| Bulb | ❓ | |
| Black Rainbow | ❓ | |
| Chipcross | ❓ | |
| Chipolarium | ❓ | |
| Collision Course | ❓ | |
| Dodge | ❓ | |
| DVN8 | ❓ | |
| Eaty the Alien | ❓ | |
| Grad School Simulator 2014 | ❓ | |
| Horsey Jump | ❓ | |
| Knight | ❌ | |
| Mondri8 | ❓ | |
| Octopeg | ❓ | |
| Octovore | ❓ | |
| Rocto | ❓ | |
| Sens8tion | ❓ | |
| Snake | ❓ | |
| Squad | ❓ | |
| Sub-Terr8nia | ❓ | |
| Super Octogon | ❓ | |
| Super Square | ❓ | |
| The Binding of COSMAC | ❓ | |
| Turnover '77 | ❓ |
| ROM Name | Working | Flags |
|---|---|---|
| An Evening to Die For | ❓ | |
| Business Is Contagious | ❓ | |
| Chicken Scratch | ❓ | |
| Civiliz8n | ❓ | |
| Flutter By | ❓ | |
| Into The Garlicscape | ❓ | |
| jub8 Song 1 | ❓ | |
| jub8 Song 2 | ❓ | |
| Kesha Was Biird | ❓ | |
| Kesha Was Niinja | ❓ | |
| Octo paint | ❓ | |
| Octo Party Mix! | ❓ | |
| Octoma | ❓ | |
| Red October V | ❓ | |
| Skyward | ❓ | |
| Spock Paper Scissors | ❓ | |
| T8NKS | ❓ | |
| Tapeworm | ❓ | |
| Truck Simul8or | ❓ | |
| SK8 H8 1988 | ❓ | |
| Super NeatBoy | ❓ | |
| Wonky Pong | ❓ |
This links to the JCommander library, which is licensed under the Apache License, Version 2.0. The license can be downloaded from http://www.apache.org/licenses/LICENSE-2.0.html. The source code for this software is available from https://github.com/cbeust/jcommander
This links to the Apache Commons IO, which is licensed under the Apache License, Version 2.0. The license can be downloaded from http://www.apache.org/licenses/LICENSE-2.0.html. The source code for this software is available from http://commons.apache.org/io