ch8go

ch8go is a CHIP-8, SUPER-CHIP and XO-CHIP virtual machine (emulator) written in Go, created as a fun project to practice the language and explore the system. The goal is to implement an accurate system with broad ROM compatibility.

More information about CHIP-8 and the project design is available in the wiki

🌐 Try the Live Demo

Highlights

• Ease of Use: No manual setup required — quirks, tick rate, and color palette are automatically configured for each ROM using a built-in metadata database
• High accuracy: Passes all Timendus and Octo test ROMs, executed via go test and validated using golden files and continuous integration (details).

Frontends

• WASM: Runs directly in the browser using WebAssembly and is installable as PWA.
• SDL2: Runs natively using hardware-accelerated graphics.
• Ebiten: Runs natively using pure-Go graphical library with no external runtime dependencies.
• CLI: Runs headless with an interactive REPL/debugger, built-in disassembler, and ASCII display renderer.

Emulation Core

• CHIP-8: Implements all 35 standard opcodes, including timers, stack, and registers.
• SUPER-CHIP: Implements extended opcodes, high-resolution mode, 16×16 sprites, scrolling, and additional font.
• XO-CHIP: Implements extended opcodes, four-plane graphics with 16 colors, and extended audio.
• Quirks: Implements all common quirks — shift behavior, jump offsets, VF reset, screen clipping, memory behavior, VBlank waiting, half scrolling (details).

Controls

CHIP-8              Keyboard
1  2  3  C   →      1  2  3  4
4  5  6  D   →      Q  W  E  R
7  8  9  E   →      A  S  D  F
A  0  B  F   →      Z  X  C  V

CLI Usage

Run the CLI with:

go run ./cmd/cli --rom path/to/game.ch8

Inside the prompt (ch8go>), you can use the following commands:

Command	Description
help	Show all supported commands
load <file>	Load a ROM into memory
step <n>	Execute 1 or N instructions
peek <n>	Disassemble 1 or N instructions starting from PC
regs	Show registers
dis	Disassemble the loaded ROM
draw	Render the current display buffer in ASCII
info	Show metadata about a ROM
quit	Exit the REPL

Example session

❯ go run ./cmd/cli --rom ./roms/test_opcode.ch8
ch8go CLI. Type 'help' for commands.
ROM loaded (478 bytes).

ch8go> peek 2
0200: 124E  JP  24E
024E: 6801  LD  V8, 01

ch8go> step
0200: 124E  JP  24E

ch8go> regs
PC=03DC I=0202 V=[1 3 7 0 0 42 137 236 44 48 52 26 0 0 0 0]

References

Useful resources for CHIP-8 development:

• Technical Reference
• CHIP-8 Research Facility
• Opcode Table
• Instruction Set
• CHIP-8 on the COSMAC VIP
• Mastering SUPER-CHIP
• XO-CHIP Specification
• Timendus' test ROMS
• CHIP-8 Database
• CHIP-8 Archive
• Awesome CHIP-8

Acknowledgements

This project is made possible by the work and documentation of the community:

• The original CHIP-8, SUPER-CHIP, and XO-CHIP specifications and their authors, as listed in References section
• Game authors, including participants of Octo Jam, for making their work publicly available
• Test ROM authors, Timendus and the Octo project
• The Go, WebAssembly, Ebiten, and SDL ecosystems for providing robust tooling and libraries