https://github.com/tufteddeer/chip8stuff

Basic CHIP-8 interpreter in Rust
https://github.com/tufteddeer/chip8stuff

Last synced: 7 days ago
JSON representation

Basic CHIP-8 interpreter in Rust

• Host: GitHub
• URL: https://github.com/tufteddeer/chip8stuff
• Owner: tufteddeer
• Created: 2023-07-20T18:50:00.000Z (over 1 year ago)
• Default Branch: main
• Last Pushed: 2023-07-21T14:01:43.000Z (over 1 year ago)
• Last Synced: 2024-11-07T05:14:32.654Z (about 2 months ago)
• Language: Rust
• Size: 135 KB
• Stars: 0
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: Readme.adoc

Awesome Lists containing this project

README

        
= chip8stuff

:experimental:

Simple interpreter to execute https://en.wikipedia.org/wiki/CHIP-8[CHIP-8] games.

Capable of creating standalone executables with embedded ROM files, even after compile time.

Passes the https://github.com/Timendus/chip8-test-suite[Timendus/chip8-test-suite] tests (except for the _display wait_ quirk).

The sound timer and playback is not implemented yet, since I have not yet tested any rom that makes use of it.

Rendering is done using the https://github.com/parasyte/pixels[Pixels] crate.

All features are tested only on Linux and X11.

== Usage

Pass the rom file via command line argument

[source, shell]

----

./chip8stuff 

----

Use `--paused` to start the debugger in paused mode, allowing you to single-step right from the start.

[source, shell]

----

./chip8stuff  --paused

----

=== Creating standlone executables with embedded ROM file

You can use the `--embed` command to create a copy of the executable that will include the given ROM file, so it can be executed directly without depending on a separate ROM file. The ROM will be appended to the ELF executable, followed by a trailer consisting of the magic value `0xC8` and the length of the ROM as `u16` (_big endian_).

The new executable will be placed in the current working directory with the name `chip8stuff__player`

[source, shell]

----

./chip8stuff --embed 

# run the new executable

./chip8stuff__player

----

See `--verbose` for detailed logging and `--help` for usage help.

== Input

The original hex keypad

[width=25%]

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

| kbd:[1] | kbd:[2] | kbd:[3] | kbd:[C]

| kbd:[4] | kbd:[5] | kbd:[6] | kbd:[D]

| kbd:[7] | kbd:[8] | kbd:[9] | kbd:[E]

| kbd:[a] | kbd:[0] | kbd:[B] | kbd:[F]

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

is mapped to the keyboard as following:

[width=25%]

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

| kbd:[1] | kbd:[2] | kbd:[3] | kbd:[4]

| kbd:[Q] | kbd:[W] | kbd:[E] | kbd:[R]

| kbd:[A] | kbd:[S] | kbd:[D] | kbd:[F]

| kbd:[Y] | kbd:[X] | kbd:[C] | kbd:[V]

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

== Debug features

- view register values

- view executed instructions

- pause execution/single step

- dump memory to a file, the exact file name will be printed on `stdout` at `info` level

image::docs/debug_screenshot.png[]