An Octo compatible XO Chip, Super Chip, and Chip 8 emulator.

1. What is it?
2. License
3. Compiling
4. Running
   1. Requirements
   2. Starting the Emulator
   3. Running a ROM
   4. Screen Scale
   5. Instructions Per Second
   6. Quirks Modes
      1. Shift Quirks
      2. Index Quirks
      3. Jump Quirks
      4. Clip Quirks
      5. Logic Quirks
   7. Memory Size
   8. Colors
5. Customization
   1. Keys
   2. Debug Keys
6. ROM Compatibility
7. Third Party Licenses and Attributions
   1. JCommander
   2. Apache Commons IO

This project is a Chip 8 emulator written in Java. There are two other versions of the emulator written in different languages:

• Chip8Python
• Chip8C

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 XO Chip and Super Chip specifications. Note that while there are no special flags that are needed to run an XO Chip, Super Chip, or normal Chip 8 ROM, there are other compatibility flags that may need to be set for the ROM to run properly. See the Quirks Modes documentation below for more information.

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 17 or greater installed (note that these steps are only needed if you want to compile the software yourself - if you just want to run the emulator, see the Running section below).

1. For Linux - the simplest way to install the JDK is to use OpenJDK:

   sudo apt update sudo apt install openjdk-17-jdk

2. For Windows - I recommend using Eclipse Temurin (formerly AdoptJDK) as the software is licensed under the GNU license version 2 with classpath exception. The latest JRE builds are available at https://adoptium.net/en-GB/temurin/releases (make sure you select JDK as the type you wish to download). The MSI method will download an installer that will download and can be run to install the JDK for you. Follow the prompts for more information. Note that this will also install the appropriate JRE as well.

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-2.0.2-all.jar.

The project needs several different packages installed in order to run the emulator properly. Please see the platform specific steps below for more information.

You will need to install the Java Runtime Environment (JRE) 17 or higher.

1. Java Runtime Environment (JRE) version 17 or higher. The simplest way to do this is to install OpenJDK 17 or higher. On Ubuntu or Debian systems, this can be done with :

   sudo apt update sudo apt install openjdk-17-jre

2. Check that installation was successful by typing:

   java -version

You will need to install the Java Runtime Environment (JRE) 17 or higher.

1. I recommend using Eclipse Temurin (formerly AdoptJDK) as the software is licensed under the GNU license version 2 with classpath exception. The latest JRE builds are available at https://adoptium.net/en-GB/temurin/releases (make sure you select JRE as the type you wish to download). The MSI method will download an installer that will download and can be run to install the JRE for you. Follow the prompts for more information.

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-2.0.2-all.jar 

The command-line interface currently requires a single argument, which is the full path to a Chip 8 ROM:

java -jar emulator-2.0.2-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-2.0.2-all.jar /path/to/rom/filename --scale 10 

The command above will scale the window so that it is 10 times the normal size.

The --ticks switch will limit the number of instructions per second that the emulator is allowed to run. By default, the value is set to 1,000. Minimum values are 200. Use this switch to adjust the running time of ROMs that execute too quickly. For Super Chip 8 or XO Chip 8 ROMs, you will probably want to execute more instructions per second. For simplicity, each instruction is assumed to take the same 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 --index_quirks flag controls whether post-increments are made to the index register following various register based operations. For load (Fn65) and store (Fn55) register operations, the original specification for the Chip8 language results in the index register being post-incremented by the number of registers stored. With the Super Chip8 specification, this behavior is not always adhered to. Setting --index_quirks will prevent the post-increment of the index register from occurring after either of these instructions.

The --jump_quirks controls how jumps to various addresses are made with the jump (Bnnn) instruction. In the original Chip8 language specification, the jump is made by taking the contents of register 0, and adding it to the encoded numeric value, such as:

PC = V0 + nnn 

With the Super Chip8 specification, the highest 4 bits of the instruction encode the register to use (Bxnn) such. The behavior of --jump_quirks becomes:

PC = Vx + nn 

The --clip_quirks controls whether sprites are allowed to wrap around the display. By default, sprits will wrap around the borders of the screen. If turned on, then sprites will not be allowed to wrap.

The --logic_quirks controls whether the F register is cleared after logic operations such as AND, OR, and XOR. By default, F is left undefined following these operations. With the flag turned on, F will always be cleared.

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_0 specifies the background color. This defaults to 000000.
• --color_1 specifies bitplane 1 color. This defaults to FF33CC.
• --color_2 specifies bitplane 2 color. This defaults to 33CCFF.
• --color_3 specifies bitplane 1 and 2 overlap color. This defaults to FFFFFF.

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:

The Chip8Java emulator maps them to the following keyboard keys by default:

Pressing a debug key at any time will cause the emulator to enter into a different mode of operation. The debug keys are:

Here are the list of public domain ROMs and their current status with the emulator, along with links to public domain repositories where applicable.

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