/Chip8Python

A Super Chip 8 emulator written in Python

Primary LanguagePythonMIT LicenseMIT

I (FerdinandoPH) cloned craigthomas' Yet Another (Super) Chip 8 Emulator and made some fixes and features to it.

Fixes

  • Timers now work correctly in SUPER CHIP-8 mode
  • Substracting two registers with equal values doesn't make the result underflow to 0x100 anymore, now it stays at 0x0
  • Added the SUPER CHIP-8 font

Features

  • Some operations behave differently in newer interpreters, so I added a flag to switch between the old and new behaviors
  • Added a window to select the ROM instead of having to type the path in the command line
  • Added a debugger (pressing esc)
  • Added sound
  • Added save states (F5 to save, F7 to load)


This is the original README.md file from craigthomas' repository:

Yet Another (Super) Chip 8 Emulator

Table of Contents

  1. What is it?
  2. License
  3. Installing
    1. Ubuntu Installation
    2. Windows Installation
  4. Running
    1. Running a ROM
    2. Screen Scale
    3. Execution Delay
  5. Customization
    1. Keys
    2. Debug Keys
  6. ROM Compatibility
  7. Further Documentation

What is it?

This project is a Chip 8 emulator written in Python 3.6+. The original purpose of the project was to create a simple learning emulator that was well documented and coded in terms that were easy to understand. It was also an exercise to learn more about Python. The result is a simple command-line based Chip 8 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.

There are two other versions of the emulator written in different languages:

License

This project makes use of an MIT style license. Please see the file called LICENSE.

Installing

Copy the source files to a directory of your choice. In addition to the source, you will need the following required software packages:

I strongly recommend creating a virtual environment using the virtualenv builder as well as the virtualenvwrapper tools. With these tools, you can easily create a virtual sandbox to install pygame and run the emulator in, without touching your master Python environment.

Ubuntu Installation

The installation under Ubuntu 20.04 requires several different steps:

  1. Install SDL libraries. The SDL (Simple DirectMedia Layer) libraries are used by PyGame to draw images on the screen. Several other dependencies are needed by SDL in order to install PyGame. To install the required SDL libraries (plus dependencies) from the command-line:

    sudo apt install python3 python3-dev libsdl-dev libfreetype6-dev \
libsdl-image1.2-dev libsdl-mixer1.2-dev libsdl-ttf2.0-dev libsdl-sound1.2-dev \
libportmidi-dev

  2. Install PIP. The pip package manager is used for managing Python packages. To install pip from the command-line:

    sudo apt install python3-pip

  3. (Optional) Install virtual environment support for Python:

    1. Install virtual environment support:
    pip3 install virtualenv
pip3 install virtualenvwrapper
    1. First you must update your .bashrc file in the your home directory and add a few lines to the bottom of that file:
    cat >> ~/.bashrc << EOF
export VIRTUALENVWRAPPER_PYTHON=/usr/bin/python3
export WORKON_HOME=$HOME/.virtualenvs
export PATH=$PATH:$HOME/.local/bin
source $HOME/.local/bin/virtualenvwrapper.sh
EOF
    1. Next you must source the .bashrc file:
    source ~/.bashrc
    1. Finally you can create the environment:
    mkvirtualenv chip8

  4. Clone (or download) the Chip 8 emulator project:

    sudo apt install git
git clone https://github.com/craigthomas/Chip8Python.git

  5. Install the requirements from the project:

    pip install -r requirements.txt

Windows Installation

  1. Download and install Python 3.6.8 for Windows. Make sure that pip and Add python.exe to Path options are checked when performing the installation. Later versions of Python 3 are also likely to work correctly with the emulator.

  2. (Optional) Install virtual environment support for Python. Run the following commands from a command prompt:

    1. Install the virtual environment wrapper:
    pip install virtualenv
pip install virtualenvwrapper-win
    1. Create a new environment for the Chip 8 emulator:
    mkvirtualenv chip8

  3. Install Git for Windows.

  4. Clone (or download) the source files from GitHub. Run the following commands in a command prompt window:

    git clone https://github.com/craigthomas/Chip8Python.git

  5. Install the requirements for the project. Run the following commands in a command prompt window in the directory where you cloned or downloaded the source files:

    pip install -r requirements.txt

Running

Running a ROM

Note that if you created a virtual environment as detailed above, you will need to workon that environment before starting the emulator:

workon chip8

The command-line interface requires a single argument, which is the full path to a Chip 8 ROM. Run the following command in the directory where you cloned or downloaded the source files:

python yac8e.py /path/to/rom/filename

This will start the emulator with the specified ROM.

Screen Scale

The --scale switch will scale the size of the window (the original size at 1x scale is 64 x 32):

python yac8e.py /path/to/rom/filename --scale 10

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

Execution Delay

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,

python yac8e.py /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).

Customization

The file chip8/config.py contains several variables that can be changed to customize the operation of the emulator. The Chip 8 has 16 keys:

Keys

The original Chip 8 had a keypad with the numbered keys 0 - 9 and A - F (16 keys in total). Without any modifications to the emulator, the keys are mapped as follows:

Chip 8 Key Keyboard Key
1 4
2 5
3 6
4 7
5 R
6 T
7 Y
8 U
9 F
0 G
A H
B J
C V
D B
E N
F M

If you wish to configure a different key-mapping, simply change the KEY_MAPPINGS variable in the configuration file to reflect the mapping that you want. The pygame.key documentation contains a list of all the valid constants for keyboard key values.

Debug Keys

In addition to the key mappings specified in the configuration file, there are additional keys that impact the execution of the emulator.

Keyboard Key Effect
ESC Quits the emulator

ROM Compatibility

Here are the list of public domain ROMs and their current status with the emulator, along with keypresses based on the default keymap:

ROM Name Works Correctly Notes
MAZE ✔️
MISSILE ✔️ U fires
PONG ✔️ 4 left player up, 7 left player down, V right player up, B right player down
TANK ✔️ R fires, T moves right, 7 moves left, 5 moves down, U moves up
TETRIS ✔️ R moves left, T moves right, Y moves down, 7 rotates
UFO ✔️ R fires up, T fires right, 7 fires left

Further Documentation

The best documentation is in the code itself. Please feel free to examine the code and experiment with it.