https://github.com/Arwalk/ChipZ

A simple Chip8 emulator (executable and library) written in Zig.
https://github.com/Arwalk/ChipZ

chip-8 chip8 ziglang

Last synced: about 2 months ago
JSON representation

A simple Chip8 emulator (executable and library) written in Zig.

• Host: GitHub
• URL: https://github.com/Arwalk/ChipZ
• Owner: Arwalk
• License: mit
• Created: 2021-04-13T14:02:10.000Z (about 3 years ago)
• Default Branch: master
• Last Pushed: 2022-12-10T23:27:55.000Z (over 1 year ago)
• Last Synced: 2024-02-01T20:18:20.738Z (5 months ago)
• Topics: chip-8, chip8, ziglang
• Language: Zig
• Homepage:
• Size: 78.1 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • License: LICENSE

Lists

• awesome-zig - Arwalk/ChipZ
• awesome-zig - ChipZ🗒️A simple Chip8 emulator (executable and library) written in Zig

README

        
= 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 https://tobiasvl.github.io/blog/write-a-chip-8-emulator/[This guide] for the Chip 8 emulation itself, and https://dev.to/fabioarnold/setup-zig-for-gamedev-2bmf[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.

- https://github.com/corax89/chip8-test-rom[test_opcode.ch8] is a a general test for Chip 8 emulators

- https://github.com/daniel5151/AC8E/tree/master/roms[bc_test.ch8] is another general test file for Chip 8 emulators

- https://github.com/loktar00/chip8/tree/master/roms[IBM Logo.ch8] was found at this link (many interesting roms here!) and is just a display test

- https://github.com/Skosulor/c8int[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:

[source, zig]

----

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: 

.keys

[width="40%"]

|=============

|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.