Skip to content

Latest commit

 

History

History
188 lines (156 loc) · 7.33 KB

README.md

File metadata and controls

188 lines (156 loc) · 7.33 KB
Raw

Chip8-Emu

Chip8-Emu is a C++ program that allows a computer to interpret and run Chip-8 programs. Standard Chip-8 instructions are implemented.

Requirements

Chip8-Emu depends on the following libraries:

Building the code

From the chip8-emu directory,

mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="/path/to/openssl" ..

Usage

After building the code, a Chip-8 program ('ROM') can be run as:

./chip8 --play /PATH/TO/ROM

A library of known Chip-8 ROMs can be searched for info about the ROM, which prints some information about the ROM (if present):

./chip8 --info /PATH/TO/ROM

Controls:

  • ESC: quit Chip8-Emu.
  • Mapping from user keyboard to Chip8-Emu keyboard:
User keyboard Chip-8 keyboard
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

Chip8-Emu options:

  • -p (--play) [ /PATH/TO/ROM ]: run a Chip-8 program (ROM); will print info if it's in the known ROMs.
  • -i (--info) [ /PATH/TO/ROM ]: print info about a ROM, if it's in the known ROMs.
  • -wy (--wrap-around-y) [ on; off; default=off; ]: whether to wrap around in y-direction; required off for some games to run correctly (e.g. BLITZ) and on for others (e.g. VERS).
  • -br (--background-red-pixel-value) [ integer in the range [0, 255]; default=0; ]: red pixel value for background.
  • -bg (--background-green-pixel-value) [ integer in the range [0, 255]; default=0; ]: green pixel value for background.
  • -bb (--background-blue-pixel-value) [ integer in the range [0, 255]; default=0; ]: blue pixel value for background.
  • -fr (--foreground-red-pixel-value) [ integer in the range [0, 255]; default=1; ]: red pixel value for foreground.
  • -fg (--foreground-green-pixel-value) [ integer in the range [0, 255]; default=1; ]: green pixel value for foreground.
  • -fb (--foreground-blue-pixel-value) [ integer in the range [0, 255]; default=1; ]: blue pixel value for foreground.
  • -cs (--color-scheme) [ black-white (bw), white-black (wb), grays (gr), gameboy (gb), blue-white (blw); default=bw ]: color scheme for background and foreground.
  • -h (--help): print help menu.

Tips

  • DEBUG build of Chip8-Emu enables stepping through execution of the program while printing information that can be useful when debugging, including description of the current state, next instruction, and the display buffer ('screen'). An example is shown below:

  • Finding ROMs: a selection of public domain Chip-8 ROMs is included in the roms directory; a comprehensive library of public domain Chip-8 software can be found at the CHIP-8 Archive. A web search can turn up additonal Chip-8 software.

Disclaimers

  • Chip8-Emu is tested only for macOS at this time.
  • Some Chip-8 software is written assuming mutually incompatible convention for wrap-around in the y-direction, due to loose specification of Chip-8 standard (more discussion is here). Chip8-Emu provides an option -wy (--wrap-around-y) to toggle the y-wrap-around behavior (it can be set to on or off).

Author

Michael E. Rowan — mrowan137 — [email protected].

License

MIT License.

References

There are many excellent resources on Chip-8, and wonderful interpreters scattered about; these were especially helpful in my own quest to build a Chip-8 emulator:

These tutorials and discussions were very helpful with OpenGL, GLFW, and GLEW for graphics:

These resources were very helpful in getting working audio:

These resources provided useful discussion on OpenSSL and hashing: