A fully-featured, cross platform XO-CHIP/S-CHIP/CHIP-8 emulator written in C and SDL.

JAXE (Just Another XO-CHIP/CHIP-8 Emulator)

Brix Space Invaders (In Debug Mode)
Black Rainbow DVN8
Super Neat Boy Chicken Scratch

CHIP-8 was a virtual machine/programming language developed by Joseph Weisbecker for the COSMAC VIP in the 1970s. It was designed with 35 opcodes and resembles assembly language, but was made for the easier development of video games on the VIP.

Today, it is a popular target to be emulated because of its simplicity and charm.

Features

  • Fully implemented instruction set (including S-CHIP and XO-CHIP)
  • HI-RES (128x64) mode to support S-CHIP programs
  • Dual display buffers to support XO-CHIP programs
  • Accurate delay and sound timers
  • Extended sound (though can sometimes be a bit noisy)
  • Integrated graphical debugger allowing user to step forward and back through program execution
  • Adjustable CPU/timer/refresh frequencies, display scale, colors, and program start address
  • Toggle S-CHIP "quirks" for compatibility with a wide variety of ROMs
  • Save and load memory dumps
  • Unit tests for those writing a C emulator
  • Emulator decoupled from any particular graphics/media library allowing for easy embedding into other C programs

Technical Info

The original CHIP-8 virtual machine was designed with the following specs:

  • 35 opcodes
  • 4kb RAM
  • 16 8-bit general purpose registers
  • 16-bit program counter, stack pointer, and index registers
  • 8-bit delay and sound timer registers
  • 64x32 monochrome display
  • 16-key keypad (0-F)
  • Program memory starting at address 0x200

Due to the way CHIP-8 was designed, the "flicker" that happens when sprites are drawn is normal. Games developed for it also rarely made any attempt to cap their frame rate due to the slow hardware of the time hence the need to artificially slow the CPU down on modern emulators.

In the early 90s, Andreas Gustafsson created a port for the HP48 calculator which was eventually superseded by S-CHIP 1.0/1.1 created by Erik Bryntse. The S-CHIP added several features as well as accidentally (or intentionally?) modifying the behavior of several original opcodes:

  • 9 new opcodes
  • 128x64 HI-RES display
  • Persistent storage
  • Modified Bnnn, Fx55, Fx65, Dxyn, 8xy6, and 8xyE instructions

With time it seems the S-CHIP became more popular and many programs were written to work with its various quirks. Thus, JAXE defaults to original S-CHIP design however many of its quirks can be toggled for improved compatibility using the flags in the Options section below.

However, recently John Earnest designed the XO-CHIP extension allowing CHIP-8 programs to take advantage of modern hardware to an extent. This extension adds several more instructions and features including:

  • 7 new opcodes
  • 16-bit addressing for a total of ~64kb RAM
  • Second display buffer allowing for 4 colors instead of the typical 2
  • Improved sound support
  • Modified Fx75 and Fx85 instructions to allow for 16 user flags instead of typical 8

JAXE currently supports all of these extensions.

It should also be noted that JAXE stores its fonts in memory starting at address 0x0000 followed immediately by large fonts and finally immediately by the stack. Therefore the stack pointer initially points to address 0x00F0.

TODO

  • Continue to improve sound
  • Continue to immprove Windows support
  • Improve build procedures
  • Add more color themes

Requirements

  • SDL2
  • SDL2_ttf (for debug mode)
  • CMake (for automatic build)

Build Procedures

Linux/Windows (MinGW)

mkdir build && cd build
cmake -B. --config Release --target jaxe ..
make jaxe

Windows (non-MinGW)

Unknown at this time. Currently the code uses the POSIX getopt() function to handle command-line arguments. To build without MinGW, remove #define ALLOW_GETOPTS from the top of main.c which will unfortunately remove command-line arguments until I handle them in a portable way.

Unit Tests (Debug Must Be Set)

mkdir build && cd build
cmake -B. --config Debug --target test ..
make test

Run

Linux

./jaxe [options] <path-to-rom/dump-file>
./test (for unit tests)

Windows

If built with MinGW, command line options are available:
jaxe.exe [options] <path-to-rom/dump-file>

Otherwise:
jaxe.exe <path-to-rom/dump-file>

test.exe (for unit tests)

Options

-x Enable compatibility mode (disables all S-CHIP quirks but keeps HI-RES and new instructions)
-d Enable debug mode
-m Load dump file instead of ROM
-p Set program start address (in hex)
-c Set CPU frequency (in Hz, value of 0 means uncapped)
-t Set timer frequency (in Hz, value of 0 means uncapped)
-r Set screen refresh frequency (in Hz, value of 0 means uncapped)
-s Set display scale factor
-b Set background color (in hex)
-f Set plane1 color (in hex)
-k Set plane2 color (in hex)
-n Set overlap color (in hex)

Also includes flags for disabling specific S-CHIP "quirks" (which are all enabled by default):

-0 Disable uninitialized RAM
-1 Disable 8xy6/8xyE bug
-2 Disable Fx55/Fx65 bug
-3 Disable Bnnn bug
-4 Allow big sprites to be drawn in LO-RES mode
-5 Clear display when 00FE/00FF execute
-6 Allow sprite wrapping
-7 Disable collision enumeration
-8 Disable collision check with bottom of screen

Controls

Keyboard (This maps to the key layouts below)

1 2 3 4
Q W E R
A S D F
Z X C V

COSMAC VIP Keypad

1 2 3 C
4 5 6 D
7 8 9 E
A 0 B F

HP48 Keypad

7 8 9 /
4 5 6 *
1 2 3 -
0 . _ +

Other Controls

Key Action
SPACE Pause/Unpause
UP Step Forward (DBG Mode Only)
DOWN Step Back (DBG Mode Only)
RIGHT Increase CPU Speed
LEFT Decrease CPU Speed
ENTER Save/Create Dump File
BACKSPACE Cycle Color Themes
ESC Reset Emulator

Troubleshooting

  • This emulator defaults to S-CHIP mode, which has become more popular since the 90s. Unfortunately, S-CHIP changed the behavior of several instructions and introduced some other quirks, making some programs developed for the original COSMAC VIP not backwards-compatible. If a ROM is not working correctly (especially one written before 1990), try enabling compatibility mode with the -x flag.
  • If running a program developed for Octo, you should also enable compatibility mode with the -x flag since Octo ignores all S-CHIP quirks.
  • This emulator defaults to 0x200 as the start address, however some programs assume other defaults (namely, those written for the ETI-660 which default to 0x600). Try to find out what default address the program assumes and set that with the -p option.
  • If a program is running very slowly, try increasing the CPU speed or even uncapping it (by setting the -c option to 0). Some ROMs are developed around an uncapped execution frequency and will run much more smoothly.
  • There are many CHIP-8 variants and this emulator does not support all of them. If a ROM still does not work correctly after trying the suggestions above, it may have been written for an unsupported variant and thus will simply not work.

Contributing

Anyone is welcome to contribute! I will try to review pull requests as quickly as possible.

License

JAXE is licensed under the MIT license so you are free to do almost whatever you please with this code (see LICENSE file).

ROMs

References

Acknowledgements

Owner
Kurtis Dinelle
I like to code stuff.
Kurtis Dinelle
Similar Resources

CQC (Charmed Quark Controller) a commercial grade, full featured, software based automation system. CQC is built on our CIDLib C++ development system, which is also available here on GitHub.

The CQC Automation System What It Is CQC is a commercial quality, software based automation system, suitable for residential or commercial application

Dec 13, 2022

Emulation of classic VA synths of the late 90s/2000s that featured the Motorola 56300 family DSP

Gearmulator Emulation of classic VA synths of the late 90s/2000s that used the Motorola 56300 family DSP This project aims at emulating various musica

Jan 5, 2023

A tiny but (will be) featured rasterizer

A tiny but (will be) featured rasterizer

Introduction This is my own rasterizer implementation. Developed in C++17. Usage compile ./rasterizer [model], model names plz refer to this README Ro

Aug 22, 2022

OpenToonz - An open-source full-featured 2D animation creation software

OpenToonz 日本語 What is OpenToonz? OpenToonz is a 2D animation software published by DWANGO. It is based on Toonz Studio Ghibli Version, originally deve

Jan 2, 2023

Simple, fully external, smart, fast, JSON-configurated, feature-rich Windows x86 DLL Memory Dumper with Code Generation. Written in Modern C++.

altdumper Simple, fully external, smart, fast, JSON-configurated, feature-rich Windows x86 DLL Memory Dumper with Code Generation. Written in Modern C

Sep 9, 2022

Free,Open-Source,Cross-platform agent and Post-exploiton tool written in Golang and C++, the architecture and usage like Cobalt Strike

Free,Open-Source,Cross-platform agent and Post-exploiton tool written in Golang and C++, the architecture and usage like Cobalt Strike

Khepri Free,Open-Source,Cross-platform agent and Post-exploiton tool written in Golang and C++ Description Khepri is a Cross-platform agent, the archi

Jan 3, 2023

The Leap Motion cross-format, cross-platform declarative serialization library

Introduction to LeapSerial LeapSerial is a cross-format, declarative, serialization and deserialization library written and maintained by Leap Motion.

Jan 17, 2022

Gamepad support for SFML based on XInput and the game controller DB for SDL

SFML_GamepadSupport Gamepad support for SFML based on XInput and the game controller DB for SDL Installation Download the latest gamecontrollerdb.txt

Apr 17, 2022

Une version graphique du célèbre jeux "Othello Reversi" réalisée par la SDL et le langage C

Othello-Reversi Une version graphique du célèbre jeux "Othello Reversi" réalisée par la SDL et le langage C Remarques: Le projet peut ne pas fonctionn

Dec 24, 2021
Comments
  • Replace sprintf with snprintf

    Replace sprintf with snprintf

    Even though *_path have an apparently sufficient length, in reality some OSes like GNU/Hurd have no real limit on path length. Even when limit is real it doesn't limit the length of command line argument. We don't want to get buffer overflow with a crash. Just use snprintf as safety

Lightweight, cross-platform & full-featured shader IDE
Lightweight, cross-platform & full-featured shader IDE

SHADERed is a lightweight tool for writing and debugging shaders. It is easy to use, open source, cross-platform (runs on Windows, Linux & Web).

Dec 30, 2022
CHIP-8 Emulator using C and SDL2
CHIP-8 Emulator using C and SDL2

CHIP-WALO Intro CHIP-8 is an interpreted programming language which was initially used in the late 1970s. It was made to allow more easily programed g

Nov 1, 2022
Freeze OS is a cross-platform operating system emulator that runs on top of an interpreter called the Freeze interpreter.
Freeze OS is a cross-platform operating system emulator that runs on top of an interpreter called the Freeze interpreter.

Freeze OS is a cross-platform operating system emulator that runs on top of an interpreter called the Freeze interpreter. The operating system code is basically written in the Freeze programming language that is passed to the Freeze interpreter. The idea is to skip instances where the operating system needs to handle low level operators and focus on higher level stuff, like malware analysis, AI, and others.

May 2, 2022
EMUCHIP8, a CHIP-8 emulator.

EMUCHIP8 Chip-8 Demo Video This is a fun retro emulator project of mine. You can download the source code and build with MAKE, then insert your chip-8

Jan 1, 2023
A simple CHIP-8 emulator made for the purpose of studying computer organization, mainly how emulation does work.

CHIP8EMU A simple CHIP-8 emulator made for the purpose of studying computer organization, mainly how emulation does work. It was written in just a few

Nov 9, 2021
Simple emulator for the extremely popular Chip-8 Virtual Machine.
Simple emulator for the extremely popular Chip-8 Virtual Machine.

C8_Emulator [System Structure Reference] #@@@@@@@@@@@. @@@@@@@@@@@@@@@@,

Nov 6, 2021
CHIP-8 Emulator/Debugger made with C++ 17, OpenGL & ImGui.
CHIP-8 Emulator/Debugger made with C++ 17, OpenGL & ImGui.

Description (Some frames were deleted to make the GIF smaller) CHIP-8 interpreter/debugger made with C++ 17. SDL 2.0.16 for window creation, event han

Jan 7, 2022
Basic emulator for the CHIP-8 system

CHIP-8 Emulator Overview This project aims to write a small and functional CHIP-8 emulator (or more accurately an interpreter, since CHIP-8 wasn't eve

Feb 12, 2022
Cobalt Strike is a commercial, full-featured, remote access tool that bills itself as "adversary simulation software designed to execute targeted attacks and emulate the post-exploitation actions of advanced threat actors".
 	Cobalt Strike is a commercial, full-featured, remote access tool that bills itself as

COBALT STRIKE 4.4 Cobalt Strike is a commercial, full-featured, remote access tool that bills itself as "adversary simulation software designed to exe

Aug 21, 2022
SMARTmBOT - a new, customizable, scalable, and fully opensource mobile robot platform
SMARTmBOT - a new, customizable, scalable, and fully opensource mobile robot platform

The goal of this repository is to introduce a new, customizable, scalable, and fully opensource mobile robot platform, called SMARTmBOT. This repository provides a guide, and all design files and source codes so that you can build your own SMARTmBOT. SMARTmBOT can be useful for studying the basics of robotics, especially mobile robotics. It can also be used to study advanced topics such as swarm robotics.

Jan 2, 2023