Octo

Octo is a high-level assembler for the Chip8 virtual machine, complete with an environment for testing programs, and tools for sharing your creations. Read about the project on Itch.io!

Links

General information:

• Language Manual
• Frequently Asked Questions
• Beginner's Guide
• Intermediate Guide
• Programming Techniques Guide
• Metaprogramming Cookbook
• SuperChip Extensions
• XO-Chip Extensions
• OctoJam an Octo-centric game jam held every October.
• Chip-8 Archive A curated gallery of Chip-8 Programs.

Third-party tools and references:

• Mastering Chip-8 the most accurate Chip-8 reference online.
• HP48 SuperChip research into the quirks and behavior of SuperChip.
• Sublime Text syntax definitions
• Atom syntax definitions
• Emacs syntax definitions
• Vim syntax definitions (Octo also has Vim keybindings; see Options → Keyboard Configuration)
• VSCode syntax definitions/integration
• OctoFont .TTF font converter.
• wernsey chip8 an alternative assembler/disassembler.
• EZ-Bake Animator a graphics preparation tool.
• EZ-Writer a text preparation tool.
• EZ-Pack an image slicing/repaletting tool.

Third-party games, programs and libraries:

• KNIGHT by Simon Klit-Johnson. (Game)
• OCTOPEG by Chromatophore. (Game)
• Masquer8 by Chromatophore. (Game)
• Glitch Ghost by Jackie Kircher. (Game)
• CosmacCalc a COSMAC VIP spreadsheet built with Octo.
• Misc Samples small programs by Björn Kempen.
• Stack reusable stack data structure.
• Chip8-multiply reusable multiplication routines.
• Octo-Lfsr64 reusable PRNG implementation.

If you've built a project on, with, or for Octo and you'd like to have a link added to this list, submit a pull request!

Command Line Mode

The Octo assembler can also be used as a command-line tool via a Node.js frontend:

$ ./octo
usage: octo [--decompile] [--options <file.json>] <source> [<destination>]
       if <source> has a .gif extension, unpack an existing octo cartridge.
       if <destination> has a .gif extension, create an octo cartridge file.
       if <destination> has an .html extension, create a standalone HTML5 build.
       if the specified options file does not exist, a new template will be created.

$ cat simple.8o
	: main
		va := 1
		vb := 2

$ ./octo simple.8o simple.ch8

$ hexdump simple.ch8
	0000000 6a 01 6b 02
	0000004

The --decompile option can be used to send an existing Chip8 binary through Octo's general-purpose decompiler.

The --options option allows you to specify a JSON file with settings for all of Octo's feature flags and palette configuration, which will be used for exports and as hints during decompilation. If the specified file does not exist, a template will be created with default settings.

If you're interested in using Octo from the command line, you might like c-octo.

Sharing Your Programs

Octo has a share feature which stores source code and configuration metadata and produces a URL you can share with others. By default, Octo stores programs in its own backend, indexed based on a key.

Using the "Save HTML" button in the "Binary Tools" panel of the toolbox, you can generate a single HTML file containing the Octo emulator and your program, allowing you to easily host a game yourself or on sites like Itch.io. Octo can be configured to offer adaptive multitouch controls, making your games playable on mobile devices and tablets!

Octo can also save "Cartridges" which embed programs and their metadata in an animated GIF. Cartridges are easy to share via email or image hosting sites, and include the source code of your programs, so others can riff on your creations:

Finally, Doct is an experimental tool for building standalone binaries which run Octo programs. Give it a whirl!

Licensing

Octo, along with all its associated documentation, examples and tooling, are made available under the MIT license. See LICENSE.txt for additional details. If for any reason this is insufficiently flexible or permissive for some application, please contact John Earnest with your request. Contributions to this repository are welcome, with the understanding that they will fall under the same licensing conditions.