View Source Chip8 (chip8 v1.0.0)
Core library for a Chip-8 interpreter.
This library only handles the core logic to run Chip-8 programs and does not handle any I/O, which allows it to be easily embedded into a UI.
Created by Joseph Weisbecker in the mid-1970s, Chip-8 is a programming language composed of hexadecimal instructions and are executed on the fly by a virtual machine. The language was created to make it easier to develop video games for the COSMAC VIP microcomputer.
After becoming popular because of its simplicity, people started to implement interpreter versions for other platforms but, because the language did not have a formal specification, many of these versions some instruction had some deviations on their behavior compared to the original COSMAC VIP version.
This project follows the Cowgod's Chip-8 Technical Reference v1.0 specification and partially replicates the specification on its own documentation, being able to act as standalone documentation if needed.
usage
Usage
To run programs, you must initialize an interpreter instance
through Chip8.initialize/1
:
Chip8.initialize(program_data)
The returned interpreter instance holds all the required states for the program's execution at a given point in time. Since the instance is just a pure data structure, your application will be the one responsible to manage everything, from user interaction to managing cycles and their relation with timers.
See all Chip8
functions for more information about each operation.
Link to this section Summary
Functions
Changes the cycle rate of an interpreter.
Executes a single instruction cycle.
Shortcut to Chip8.initialize/2
.
Creates an interpreter instance with the given program loaded into its memory.
Returns a pixelmap with the current content of the display.
Computes a key press event on the hexadecimal keyboard.
Computes a key release event on the hexadecimal keyboard.
Performs the tick logic for all timers.
Link to this section Functions
@spec change_cycle_rate(Chip8.Interpreter.t(), pos_integer()) :: Chip8.Interpreter.t()
Changes the cycle rate of an interpreter.
iex> Chip8.change_cycle_rate(interpreter, 6)
%Chip8.Interpreter{}
@spec cycle(Chip8.Interpreter.t()) :: {:ok, Chip8.Interpreter.t()} | {:error, atom()}
Executes a single instruction cycle.
A cycle is composed of 3 steps: fetch the instruction from memory, decode the
instruction bytes and executes it by changing the interpreter's state.
See the cycle section at Chip8.Interpreter
for more information.
iex> Chip8.cycle(interpreter)
%Chip8.Interpreter{}
@spec initialize(bitstring()) :: Chip8.Interpreter.t()
Shortcut to Chip8.initialize/2
.
iex> program = File.read!(path)
iex> Chip8.initialize(program)
%Chip8.Interpreter{}
@spec initialize(bitstring(), Keyword.t()) :: Chip8.Interpreter.t()
Creates an interpreter instance with the given program loaded into its memory.
options
Options
cycle_rate
- amount of instructions that are going to be executed each cycle. Defaults to 10 when not specified.
iex> program = File.read!(path)
iex> Chip8.initialize(program, cycle_rate: 10)
%Chip8.Interpreter{}
@spec pixelmap(Chip8.Interpreter.t()) :: Chip8.Interpreter.Display.pixelmap()
Returns a pixelmap with the current content of the display.
This pixelmap is a list matrix with each pixel "state" of the whole display.
See Chip8.Interpreter.Display
for more information.
iex> Chip8.pixelmap(interpreter)
[[0, 0, 1, ...], [0, 0, ...], [1, ...], [...], ...]
@spec press_key(Chip8.Interpreter.t(), Chip8.Interpreter.Keyboard.key()) :: Chip8.Interpreter.t()
Computes a key press event on the hexadecimal keyboard.
See Chip8.Interpreter.Keyboard
for more information.
iex> Chip8.press_key(interpreter, 0xA)
%Chip8.Interpreter{}
@spec release_key(Chip8.Interpreter.t(), Chip8.Interpreter.Keyboard.key()) :: Chip8.Interpreter.t()
Computes a key release event on the hexadecimal keyboard.
See Chip8.Interpreter.Keyboard
for more information.
iex> Chip8.release_key(interpreter, 0xA)
%Chip8.Interpreter{}
@spec tick_timers(Chip8.Interpreter.t()) :: Chip8.Interpreter.t()
Performs the tick logic for all timers.
This function does not set timers to decrement at the required rate, only
performing the tick itself.
See Chip8.Interpreter.Timer
for more information on timers.
iex> Chip8.tick_timers(interpreter)
%Chip8.Interpreter{}