Lessons and the learning game

Write a CHIP-8 emulator

Build the classic first emulator in C++ on an ESP32-C3 handheld: memory, fetch and decode, XOR sprites, keys, timers, and an original 151-byte game.

How it works

Write a CHIP-8 emulator is an advanced Coding course in seven lessons. CHIP-8 is a computer from 1977 that only ever existed as software, with 35 instructions, a 64 by 32 screen and a 16-key pad, which makes it the emulator everyone writes first.

Every lesson runs on the handheld console: an ESP32-C3, an ILI9341 panel that shows the CHIP-8 screen at three panel pixels to one, the six-button pad and a piezo on GPIO 7. Each lesson's sketch is the emulator from the lesson before plus one new part, and each runs a ROM written for this course, as bytes with its listing in the comments.

The lessons

  1. The machine: 4 KB of memory, sixteen registers, PC, I and the stack, the hex font at 0x050 and a ROM loaded at 0x200, read back byte by byte.
  2. Fetch decode execute: two bytes, big-endian, cut into nibbles. A countdown ROM runs line by line, stops on an instruction the emulator does not know (70FF), and runs to the end once you add it. Then you edit the ROM by hand.
  3. Display: DXYN, the one drawing instruction: sprites drawn by XOR, collisions in VF, the font as labels, and a rocket whose flame you redraw in hex.
  4. Keypad: six buttons standing in for keys 2, 8, 4, 6, 5 and 0, new presses, the skip-if-held instructions, FX0A waiting for a key, and a key remapped.
  5. Timers and sound: the delay timer measured at 60 ticks to 1000 ms, a buzzer that follows the sound timer, and a ROM edit for a longer beep.
  6. Debugging ROMs: a ROM that writes BAD instead of 600D, a disassembler, and a serial debugger with step, breakpoints and registers that finds the one wrong nibble.
  7. Boss: play a game: the finale.

The catalog lists a classic ESP32, a keypad and a buzzer. The course runs on the ESP32-C3 handheld instead: Mokxi has no keypad circuit for the C3, so the handheld's six buttons stand in for the keys games use most, and its piezo is the buzzer.

The finale

Space Dodge is an original CHIP-8 game written for this course, 151 bytes of machine code. Rocks fall; left and right steer the ship. A dodged rock is a point and a short beep, a hit is the XOR collision flag, a long beep and the score in the corner from FX33 and the font. You run it, crash it on purpose, and make the rocks fall faster by changing one byte.

What the C3 engine does differently

  • Frames are paced by the clock. The emulator runs 60 frames a second, 12 CHIP-8 instructions each, and sleeps between frames, so a ROM runs at the same speed it would on a real C3.
  • The panel is bit-banged. SPI is not modeled, so the emulator sends only the pixels a sprite changes, each as a 3 by 3 square. A full CHIP-8 screen redraw would cost far more.
  • Sound is one note. tone() plays 440 Hz through the C3's LED PWM hardware while the sound timer runs, which is all the sound CHIP-8 has.
  • The ROMs are originals. Every ROM in the course was written for it. The font is the standard hex digit set every CHIP-8 interpreter carries.