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.

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

Link to this function

change_cycle_rate(interpreter, cycle_rate)

View Source
@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{}
Link to this function

initialize(program, opts)

View Source
@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{}

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, ...], [...], ...]
Link to this function

press_key(interpreter, key)

View Source

Computes a key press event on the hexadecimal keyboard.

See Chip8.Interpreter.Keyboard for more information.

  iex> Chip8.press_key(interpreter, 0xA)
  %Chip8.Interpreter{}
Link to this function

release_key(interpreter, key)

View Source

Computes a key release event on the hexadecimal keyboard.

See Chip8.Interpreter.Keyboard for more information.

  iex> Chip8.release_key(interpreter, 0xA)
  %Chip8.Interpreter{}
Link to this function

tick_timers(interpreter)

View Source
@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{}