2 Emulator usage

2.1 Installing the emulator

The main procedure for installing the emulator is to download the source code distribution, compiling it and installing it. Of course, there are aditional ways for obtaining the emulator, such as getting it from a binary distribution, for example, a .deb file for Debian based systems or an .exe application for Microsoft® Windows®.

This emulator only depends on SDL2, because it is the multimedia library used for displaying the emulator output, reading keys from the keyboard and making the speaker buzz. After the dependencies are met, this CHIP-8 emulator can be installed by downloading the software release, extracting it somewhere, and then running ./configure && make to compile it.

Once compiled, it can be installed using make install. By default on a standard GNU/Linux system they would be installed into /usr/local/bin, /usr/local/share/doc/chip8, etc. On Apple® MacOS® X systems, these locations will be used as well. On Microsoft® Windows®, the location might actually change depending on how you build the software.

If you are interested in checking that the software actually works as intended you can use the test suite provided with the source distribution. In order to run the tests you’ll need to have check installed on your computer. Install the dependencies, and then after running ./configure && make on the emulator package, run make check to run the test suite. After the execution, you will get a report on the test status.

2.2 Running the emulator

After the emulator has been downloaded it can be executed using the command chip8 file, where file is the path to a binary file that has the encoded data for a program that can run on the CHIP-8 virtual machine.

As an example, to run the ROM WIPEOFF.BIN using the emulator, the following command can be used:

$ chip8 WIPEOFF.BIN

assuming the game is on the current working directory. Some games can make use of the buzzer that the CHIP-8 computer has. The buzzer will sound through the speakers. If you want to avoid this behaviour you can run the game muted using the --mute option:

$ chip8 --mute WIPEOFF.BIN

There are actually two kinds of ROMs: binary ROMs and hexadecimal ROMs. A binary ROM only has binary data and it is the most lightweight and fast way for running a ROM because the data can be placed in memory and executed instantaneously. This data can come from a dump for an actual CHIP-8 game or a game made for the CHIP-8 platform in any other way

However, to make easier to people to create their own ROMs, there is an aditional way for running these ROMs and is using hexadecimal files. These files are plain text files only having the characters 0-9, A-F and a-f encoded as either US-ASCII, UTF-8, Windows-1252 or a similar human readable text-enconding and can be modified using any kind of text editor that supports plain text. This format is slower to load since the file has to be converted to binary but it makes playing around faster.

2.3 Using the emulator

Once the emulator opens, it automatically starts executing the ROM contents. It is possible to control the emulator using the emulated keyboard. The CHIP-8 specification sets a 16 keys keyboard using a 4x4 table having the following layout:

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

Using the current settings, that aren’t modifiable by the user yet –although that is hoped for future releases, the assigned keys for the keyboard are mapped to the following keys on a traditional keyboard:

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

Which means that if you want to send the 5 key to your game you should press the W key in the emulator. Pressing F will trigger E key and similar.

During the execution of a CHIP-8 ROM, some games may play sounds on the buzzer. As explained in Running the emulator, this behaviour can be changed by using the option --mute when running the game.

2.4 Stopping the emulation

At this moment there is no way for pausing, resuming, resetting or stopping the emulation in this CHIP-8 emulator. The only way for stopping it is by exiting the emulator, something that you can do by pressing the Close button on the emulator window. This depends on your window manager or operating system.