Chip8-Emu is a C++ program that allows a computer to interpret and run Chip-8
programs.
Standard Chip-8 instructions
are implemented.
Chip8-Emu depends on the following libraries:
From the chip8-emu directory,
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DOPENSSL_ROOT_DIR="/path/to/openssl" ..After building the code, a Chip-8 program ('ROM') can be run as:
./chip8 --play /PATH/TO/ROMA 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/ROMControls:
- 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; requiredofffor some games to run correctly (e.g. BLITZ) andonfor 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.
DEBUGbuild 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.
- 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 toonoroff).
Michael E. Rowan — mrowan137 — michael@mrowan137.dev.
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:
- Cowgod's Chip-8 Technical Reference v1.0
- David Winter's CHIP-8 emulation page
- Core Dump's Chip-8 tutorial
- dmatlack's Chip-8 Emulator (written in C)
- linoscope's Chip-8 Emulator (written in OCaml)
- mir3z's Chip-8 Emulator (written in JavaScript)
These tutorials and discussions were very helpful with OpenGL, GLFW, and GLEW for graphics:
- OpenGL begginer's tutorial
- Learn OpenGL example
- GLFW CMake tips for macOS
- Modern OpenGL tutorial
- GLFW getting started
These resources were very helpful in getting working audio:
- Apple Developer Documentation: Core Audio, Core Audio Types
- Device input using the HAL Output Audio Unit
- Multi-platform audio header
- Tone generator using Audio Units
- Using Core Audio to create real-time I/O stream on OS X
These resources provided useful discussion on OpenSSL and hashing: