# Octal Cookie

A CHIP-8 emulator / simulator written in [Odin](https://odin-lang.org/) using [Raylib](https://www.raylib.com/).

[![showcase](showcase.png)](showcase.png)

**[Try it in your browser →](https://jasonhilder.dev/sim)**

---

## About

This was my refresher project to get back into lower-level programming — specifically the [Odin](https://odin-lang.org/) language and [Raylib](https://www.raylib.com/). Building a CHIP-8 emulator felt like the right scope: small enough to actually finish, but with enough surface area (opcode decoding, memory, timers, a display, input) to shake the rust off.

It's not perfect, but it's functioning and usable for the most part. Compiles to native and to WebAssembly, and the web build is playable directly at the link above.

---

## Features

- Full CHIP-8 instruction set emulation
- Simulator GUI with dedicated panels for the screen, CPU state, keypad, file loader, memory viewer, and control bar
- Built-in collection of classic game ROMs (Pong, Tetris, Space Invaders, Brix, and more)
- Load your own ROMs via the file loader panel
- Dev and release build modes via `make`
- Compiles to WebAssembly for running in-browser

---

## Roadmap

Future work, mainly once I'm back in the headspace for it:

- General refactor/cleanup pass now that the core is working
- CHIP-8 quirks support (configurable behavior differences between interpreters)
- SUPER-CHIP instruction support

---

## Dependencies

- [Odin compiler](https://odin-lang.org/docs/install/)
- [Raylib](https://www.raylib.com/) (used via Odin's vendor bindings)
- [tinyfiledialogs](https://sourceforge.net/projects/tinyfiledialogs/) (included under `external/`)

---

## Building

```sh
# Run directly in dev mode
make

# Build a dev binary
make dev

# Build an optimised release binary
make release

# Clean build output
make clean
```

The output binary is named `my_app` by default. You can change `APP_NAME` in the `Makefile`.

---

## Included ROMs

A set of public domain game ROMs is bundled under `assets/game_roms/`:

`15PUZZLE` · `BLINKY` · `BLITZ` · `BRIX` · `CONNECT4` · `GUESS` · `HIDDEN` · `INVADERS` · `KALEID` · `MAZE` · `MERLIN` · `MISSILE` · `PONG` · `PONG2` · `PUZZLE` · `SYZYGY` · `TANK` · `TETRIS` · `TICTAC` · `UFO` · `VBRIX` · `VERS` · `WIPEOFF`

Test ROMs are available under `assets/test_roms/` for development and debugging.

---

## License

MIT — see [LICENSE](LICENSE).