<p align="center"> <img src="media/chip8.png" width="45%"> <img src="media/schip.png" width="45%"> </p> <p align="center"> <img src="media/xochip.png" width="45%"> <img src="media/megachip.png" width="45%"> </p> <p align="center"> <img src="media/hybridchip8.png" width="45%"> <img src="media/cosmac.png" width="45%"> </p>

jchip

A multi-variant CHIP-8 interpreter and COSMAC-VIP emulator written in Java.

• jchip
• Introduction
• Features
  • Variants
  • Configurable quirks
  • Debugger and Disassembler
  • Database
• Usage
  • Menus
  • Command line
• Building from Source
• Resources and general links
• Credits
• License

Introduction

After branching out to other areas of programming, I came across the world of emulation. I discovered that the first system recommended for beginners to emulate is called CHIP-8. CHIP-8 was originally a programming language ran by interpreter developed for the COSMAC-VIP computer from the late 1970s, which allowed its users to program games for it with a small and easy to understand instruction set.

Unlike most people who use CHIP-8 as a stepping stone to building actual emulators for systems like the Game Boy or NES, I found myself captivated by this small but interesting platform. I found out that CHIP-8 is just the first of a family of variants and extensions all building off of the same foundation. CHIP-8 as a platform has remained relatively alive via more modern implementations that add new features, which even allowed for game jams to be hosted for it, called OctoJams.

Thus, jchip has evolved from a rudimentary bare-bones interpreter into my first gateway into emulation and proper application development. My appreciation for CHIP-8 and its community is demonstrated by implementing as many variants as accurately as possible, while providing extra convenience features for customization, debugging, and ease of use. As a token of appreciation, jchip also includes a full-fledged COSMAC-VIP emulator variant for people who want to try out ROMs made for this computer.

Features

CHIP-8, along with the other variants supported by this emulator, were implemented using a combination of high level guides, as well as the most accurate opcode table I could find. Any small details were clarified to me by the more experienced people on the #chip-8 channel of the EmuDev discord server.

Variants

As mentioned, CHIP-8 comprises a family of variants all based on the same fundamental specification. Most variants add new instructions and functionality on top of CHIP-8, and others alter or completely replace the behavior of existing opcodes. The full list of supported variants is the following:

1. CHIP-8: An implementation of the original CHIP-8 interpreter for the COSMAC-VIP, as developed by Joseph Weisbecker. A complete documentation of CHIP-8's usage as well as its implementation on the VIP can be found in the RCA COSMAC VIP CDP18S711 Instruction Manual.
2. STRICT-CHIP-8: An HLE cycle accurate implementation of CHIP-8, modeling interrupt timings for audio, video, and timer updates. This variant also implements proper memory mapping of the CHIP-8 interpreter address space on the COSMAC-VIP. Note that this variant cannot run hybrid CHIP-8 roms, which are those that utilize instruction group 0NNN in order to call native subroutines belonging to the COSMAC-VIP itself. This variant also ignores any user configured quirks or IPF, as it strictly adheres to the original implementation and timings. The implementation of this core is heavily based on Cadmium's chip8-strict core. Many thanks to @Gulrak for letting me borrow his implementation.
3. CHIP-8X: An official extension of CHIP-8 by RCA which adds support for low and high resolution color modes for a total of 4 background colors and 8 foreground colors. It also added instructions for communicating with I/O devices, support for a second keypad, and an octal addition instruction. Note that the second keypad and I/O instructions are stubbed except for FXF8, where vX is used to set the pitch of the buzzer.
4. SUPER-CHIP-1.1: Also known as SUPER-CHIP-LEGACY in today's times, this is the last in a subset of extensions made for the HP 48 calculators. Starting with CHIP-48, which was purely a reimplementation of the original interpreter, it failed to reproduce the original behavior of several instructions, giving rise to the first quirks. SUPER-CHIP 1.0 was released for newer models of the calculator, and added a high and low resolution modes, the former expanding the display resolution to 128 by 64 pixels, the ability to draw 16 by 16 sprites, and a feature to persist the scratchpad registers onto a set of flags register which retain their values across emulator restarts. Finally, SUPER-CHIP 1.1 was an extension developed by Erik Brynste and added new scrolling instructions and an instruction to point the index register I to one of the new big font sprites now built into the interpreter.
5. SUPER-CHIP-MODERN: This variant corresponds to Octo's generic implementation of the SUPER-CHIP extension. This variant differs from its legacy counterpart as it doesn't fully emulate certain quirks, visual artifacts, and collision detection handling during execution of a DXYN instruction. As such, it is considered its own separate variant that is similar enough to SUPER-CHIP-LEGACY to fall into the SUPER-CHIP category. Note that developers using Octo that wish to target SUPER-CHIP will be using this "modern" variation instead.
6. XO-CHIP: Developed by John Earnest, it debuted alongside Octo as the most popular modernized version of CHIP-8 which most newcomers target when they start developing in Octo. Bringing a host of new features, including bit-plane based color support, an expanded addressable range of 64KB allowing ROMs to store much more data such as sprites and audio, support for audio in the form of square wave audio samples as well as controllable pitch, and new instructions for more convenient memory manipulation. Many newer games were made for this variant thanks to Octo and the Octojams hosted by John Earnest, and although Octojams are no longer being hosted, these games, along with many other programs, showcase the capability of this limited but fun fantasy console and, in my opinion, serves as a great way to get into assembly-like languages.
7. MEGA-CHIP: Published by Revival Studios in 2007, this variant is relatively obscure within the community. Due to the fact that Revival Studios failed to deliver a complete implementation, many areas of the specification remain unclarified. As such, developers looking to implement this variant are free to fill in the gaps as they please, although most of the key details have been agreed upon by the community. At first, it behaves like a half-broken implementation of SUPER-CHIP. However, it adds new instructions to enable and disable a new "mega mode", which when enabled, actives MEGA-CHIP's features. It expands the display resolution to 256 by 192 pixels, supports loading ARGB color palettes for sprite drawing along with blending modes and an alpha value (the latter being undefined in its implementation), adds the ability to play raw 8 bit synthesized audio samples, and expands the addressable range to 16MB for even more sprite and audio data. The way screen updates and scrolling also changes, and this notably becomes a huge point of confusion for new developers looking to implement this variant. Nevertheless, due to its interesting features and the handful of demos that exist for it, I decided to include this variant in my emulator, in the hopes that it may gain more popularity in the future.
8. HYPERWAVE-CHIP-64: A newer and even lesser known variant developed by @NinjaWeedle. Being an extension of XO-CHIP, this variant includes new multiplication and division instructions, three new instructions to take advantage of the expanded memory size for actual code instead of just assets, new drawing modes for more convenient display manipulation, and the ability for ROMs to load their own bit-plane based color palette, instead of relying on the host emulator to supply the colors. This variant only has a few ROMs made mostly by the variant's developer and doesn't seem to have gained much traction. However, in the spirit of supporting newer extensions, I decided to implement it as a way to show support for possible new improvements to XO-CHIP, in the hopes that it will become more popular in the future.
9. HYBRID CHIP-8: This variant is backed by an emulator implementation of the original COSMAC-VIP computer from the RCA corporation. Powered by the CDP1802 microprocessor and the CDP1861C video display interface, this variant is capable of running hybrid CHIP-8 ROMs, which are those that require the use of native subroutine calls written in CDP1802 machine language. This variant does not support custom quirks, configurable color palettes, or IPF.
10. HYBRID CHIP-8X: This variant, while also being bac