Lessons and the learning game

Game dev on microcontrollers

Write a space platformer in C++ on an ESP32-C3 with a 128x64 OLED, three buttons and a piezo, one game-dev idea at a time.

The course

Game dev on microcontrollers is an intermediate Coding course in seven lessons. Every lesson runs on the same circuit, the space platformer rig, and opens a new sketch built for one idea. Every step is checked against what the board prints, a pin it drives or the pitch on the piezo.

  1. The game loop: read, update, draw, wait. A parallax starfield at a fixed 25 frames a second, the I2C clock that eats the frame time, and a frame budget you blow (47 frames a second) and then fit (50).
  2. Sprites and frames: an 8x8 astronaut stored as eight bytes, a two frame walk cycle on its own clock, a mirrored turn that costs no memory, and erasing exactly what you drew.
  3. Input: one snapshot of the buttons a frame, held versus pressed, and why reading once every 40 ms hides contact bounce that an interrupt counts edge by edge.
  4. Collision: AABB boxes in four comparisons, crystals you collect, a boulder that stops you by undoing the move, and a hitbox tuned to feel fair.
  5. Gravity: velocity, acceleration and positions in sixteenths of a pixel. A 15 pixel jump, moon gravity at 48, and a one-way ledge you land on from above.
  6. Sound effects: note tables played by tone() from the game loop without ever blocking it, with priorities so a reward is never cut short.
  7. Boss: a platformer.

The finale

The boss is a complete game: three crystals on the moon, three floating rocks, a crater that costs a life and a portal that opens once you hold all three. It uses every lesson at once, and the level is data (FLOORS, CRYSTALS, PORTAL), so the last step is designing a level of your own: readable, fair for a 22 pixel jump, and built around one new idea.

The rig

  • An ESP32-C3 at 160 MHz with 400 KB of SRAM.
  • A 128x64 SSD1306 OLED on bit-banged I2C at 400 kHz: SCL on GPIO 5, SDA on GPIO 4.
  • Three pushbuttons to ground: LEFT on GPIO 2, RIGHT on GPIO 3, JUMP on GPIO 10, read with the chip's own pull-ups, so pressed reads LOW.
  • A piezo on GPIO 8, driven by the C3's LEDC peripheral through tone().

How the C3 engine differs

The board runs Mokxi's own firmware runtime, not the Arduino core: the same setup() and loop(), with drivers for the OLED (mokxi_ssd1306.h) that keep a 1 KB frame buffer and send only the 8x8 blocks that changed. That is why the frame time in lesson 1 depends on how much of the picture moves.

There is no floating point unit, so physics is fixed point, as it was on the consoles these games imitate. delay() parks the core instead of spinning, so a waiting game costs almost nothing to simulate and runs at full speed in the browser.

Where next