Mychip8

// README.adoc

:author: Tom Swan :email: tom@tomswan.com :description: Guide to MyChip8 for VIPS a Cosmac VIP Emulator :keywords: GAMES VINTAGE PROGRAMMING CHIP8 OCTO C++ RCA COSMAC VIP :copyright: © 2020,2022 by Tom Swan :favicon: https://www.tomswan.com/image/favicon.png :icons: font :idprefix: :idseparator: - :sectanchors: :imagesdir: image :license: LICENSE.txt[License Text] :dot: . :ellipsis: … :hatch: # :pilcrow: ¶ :star: * :tilde: ~ :ul: _

= My VIP Chip8 Emulator

by Tom Swan

Welcome to MyChip8 for VIPs, my home-brew Cosmac VIP emulator based on an open-source Chip8 interpreter (see <<original>>). I wrote, revised and tested MyChip8 with dozens of published Chip8 and Octo games and other programs. MyChip8 runs great, it's all open-source, it's all here, and it's all free.

.Br8kout image::clip-br8kout.gif[800, 500]

MyChip8 is composed of two symbiotic objects: an emulator -- encompassing the interface, graphics display, and keyboard input; and a Chip8 interpreter -- the code that loads and executes Chip8 bytecode instructions. It's built using Qt's OpenGL graphics and other C++ class libraries. This guide explains how to compile the MyChip8 source code files and shows how to use the program to load and run Chip8 programs.

NOTE: This early release of MyChip8 runs best from a terminal command-line and has only a rudimentary interface -- so far!

---

Published under the GNU General Public License (GPL) v3: link:{license}

Copyright (C) 2022 by Tom Swan

---

[cols="4*"] |=== | <<building>> | <<options>> | <<programs>> | <<linksand>> |===

// -----------------------------------------------------------------

[[releasenotes]] == MyChip8 0.1 Release Notes

.RCA Cosmac VIP image::cosmac-vip.png[float="right"]

Version 0.1 of MyChip8 as described in this manual faithfully executes Chip8 programs written for the RCA Cosmac VIP computer (circa 1970s, see photo), outputting to a fixed 32-by-64-pixel, monochrome display, and loading bytecode files into a 4096-byte virtual memory core. Additional features include the following (also see <<options>>):

• Single-step debugging mode (NEW: Press F2 to toggle!)
• Alternate keyboard keys
• Adjustable speed and display refresh rates
• Programmable pixel and window sizes
• Selectable pixel color
• All source code included

Except for the original interpreter, which I rewrote and debugged from top to bottom, I wrote all of MyChip8 from scratch in C++ using the Qt development system running on Ubuntu Linux, compiled using QMake and the Gnu Compiler Collection (GCC). (See <<resources>> for links to required software.)

MyChip8 implements all but one of the 35 original Chip8 instructions as programmed for the Cosmac VIP. MLS (CDP1802 Machine Language Subroutine) calls, are not recognized. SuperChip, Octo and other Chip8 extensions also are unimplemented--so far, but are top priorities. Check back often for updates!

NOTE: I compiled most test programs using Octo (terminal- and browser-based versions) and then executed the resulting Chip8 bytecodes using both Octo and MyChip8. Testing in both environments revealed many subtle bugs and runtime differences that I was able to mostly smooth out. As a result, authentic Chip8 programs should run identically, or at least very similarly, in both MyChip8 and Octo using default settings.

---

// -----------------------------------------------------------------

[[building]] == Building the Emulator

Download and install Qt if necessary (see <<resources>>). Next, clone the mychip8 GitHub repository into any folder. Or, if you choose the download option, unpack the downloaded ZIP file. Either way, the result is a new folder named mychip8 containing all program files. You now have two choices for building and running MyChip8:

• Build and run directly in the Qt IDE
• Run QMake and other commands in a terminal window

I use the second method in Linux, so that's what I describe here. (You can additionally build in the Qt IDE and then run the mychip8 executable file from the build folder that Qt creates.) Similar commands ought to work in Windows and on Macintosh systems, but you must first open a terminal window.

Following are the commands that I use to clone the MyChip8 repository, build the program, and run a sample Chip8 program ($ is the terminal prompt; {tilde} stands for "home folder"):

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - === Building With Terminal Commands (Linux)

.... cd git clone https://github.com/TomSwan/mychip8.git cd mychip8 mkdir build cd build ~/Qt/5.15.0/gcc_64/bin/qmake -o Makefile ../mychip8.pro -spec linux-g++ make ./mychip8 ../examples/mytank.ch8 ....

The first command navigates to the home folder -- or, you can change to any other folder for holding the repository. In the configuration command (third line from the last), edit the version numbers and operating system as needed. If MyTank runs, MyChip8 is working! Press W S A D to navigate, Esc to quit. See <<links>> if you have trouble.

.MyTank Chip8 example image::clip-mytank1.gif[640, 400]

TIP: Using Qt Creator, start a new Qt console project, build it, and then open the resulting Makefile in the project's build folder. Look for a comment documenting the proper configuration settings for console applications on your system.

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - [[buildingwithqtide]] === Building With Qt IDE (Qt Creator)

To build the program directly from the Qt IDE (Qt Creator) select File|Open File or Project... and then select and open the file mychip8/mychip8.pro. When asked to "Configure Project," select a kit such as:

---

Desktop Qt 5.15.0 GCC 64bit

and then click the Configure Project button. You only have to perform this step once. After that's done, optionally browse the source code files in the Editor, and then before running, configure the IDE for terminal-based input and output:

1. Select Projects
2. Under "Build & Run" select Desktop Run
3. Enable "Run in terminal"
4. Locate the field "Command line arguments:" under Run Settings
5. Enter a path name to a Chip8 program file, for example:

---

Command line arguments: ~/mychip8/examples/mytank.ch8

Finally, select Run to build and run MyChip8, which should load and run mytank.ch8 (W S D A to navigate; Esc to quit). Press Return to close the terminal window opened by Qt.

---

// -----------------------------------------------------------------

[[running]] == Running Chip8 Programs

For best results, compile Chip8 programs using Octo and then run the resulting bytecode file with MyChip8:

---

$ cd ~/mychip8/examples $ ~/Octo/octo mytank.8o mytank.ch8 $ ../build/mychip8 mytank.ch8

Alternatively, create soft links such as octo and mychip8 in a PATH directory. You can then omit the complex path name as in the second line below:

---

$ cd ~/mychip8/examples $ mychip8 pong2.ch8

.Pong2 Chip8 example image::clip-pong2.gif[640, 400]

TIP: See <<links>> for how to create soft links in Linux.

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - === Getting a Little Help

Once you can build MyChip8, load and run a Chip8 program such as MyTank in the examples folder and then press F1 during any program run to display the following help text on the terminal showing the PC keyboard keys (left) that correspond to the original VIP hex pad buttons (right):

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - === Chip8 Keyboard Map

---

1 2 3 4 == 1 2 3 C Q W E R == 4 5 6 D A S D F == 7 8 9 E Z X C V == A 0 B F

Some Chip-8 programs come with instructions, some don't. Many require you to figure out how to play them. Press keys and try to discover the rules. That's part of the fun of Chip8 programming!

TIP: Use the -k option to enable keyboard arrow keys in addition to the usual W A S D navigation hex pad keys.

---

// -----------------------------------------------------------------

[[options]] == Emulator Options

Call me old fashioned, but I prefer to run MyChip8 from a command-line prompt with the name of a Chip8 file to load and run. That way, I can easily select among several available runtime options.

All options are in the usual <dash><letter> format such as -v (display version) and -h (help), which also have equivalent long forms --version and --help. You may combine options in any order. For instance, this sets the pixel color to Blue and toggles debugging mode on or off depending on its default setting (usually off):

---

$ mychip8 -p blue -d mytank.ch8

You could insert -d ahead of -p, but options that need values expect to find them immediately following. Sensible abbreviations are usually okay:

---

$ mychip8 -dp red -b6 mytank.ch8

---

// -----------------------------------------------------------------

=== Function Keys

|=== | [big]#F1# | Help | [big]#F2# | Toggle Debugging |===

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - === Options Index

Enter mychip8 --help or -h for a list of available options (see screenshot). For testing and as place holders, some options are not implemented. For example, you may enter source and output filenames, but GIF creation is not yet supported and output file names currently have no purpose.

.MyChip8 help text image::screenshot.png[]

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - === -h, --help, --help-all

Displays indexed information about program options. The last variation, --help-all, displays additional information about various options for standard Qt parameters.

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - === -v, --version

Shows the current versi