README.adoc

ChipZ

This is a simple Chip8 emulator built using the Zig programming language.

This software was mostly meant to be for me to learn the basics of Zig, but it should be working for general Chip8 emulation.

This emulator was built following This guide for the Chip 8 emulation itself, and This other guide for the SDL2 setup.

Some demo files are in this repository. Here are the sources and description. All credits to the original creators.

• test_opcode.ch8 is a a general test for Chip 8 emulators

• bc_test.ch8 is another general test file for Chip 8 emulators

• IBM Logo.ch8 was found at this link (many interesting roms here!) and is just a display test

• c8_test.c8 is an excellent testing rom too, with tests on timers.

Building and running

Using the library

src/lib/chipz.zig is a file containing everything needed to start chip 8 emulation. You just need to bring the GUI part to it. For your own use, add this file as a package to your build.zig file.

For an example of how to use the library, check out main.zig or this simple example:

var general_purpose_allocator = std.heap.GeneralPurposeAllocator(.{}){};
const gpa = general_purpose_allocator.allocator();

var emu = chipz.ChipZ.init(gpa);
emu.load_program(buffer);

while (true): {
    if (emu.cycle()) {} else |_| {
        @panic("Faulting instruction");
    }
    if (emu.flags.display_update) {
        // refresh display according to the content of emu.display
    }
}

Building the main program

The ChipZ emulator relies on SDL2. You need to have the SDL2 library available in your system library path to build and run it.

It has been tested on windows and macOS(arm) successfully so far, but should work with linux too.

Running the tests

There are a few tests. zig build test will run them.

Using the emulator

To use the emulator, run "chipz.exe" and pass the rom path as a parameter (i.e chipz.exe my_path/to/my/rom.ch8).

The Chip 8 "COSMAC VIP" keyboard is mapped like this:

Table 1. keys

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

Keyboard scancodes are used so any non-qwerty keyboard should have the same mapping.

Sound isn’t managed and won’t be implemented.

Pressing the UP or DOWN key allows to resize the window.