Lessons and the learning game

Write a physics engine

Build a 2D physics engine in C++ on an ESP32-C3, from vectors and time steps to rigid bodies, ending in a tilt-driven marble sandbox.

How it works

Write a physics engine builds the engine one idea at a time, and each lesson both prints its numbers and shows them moving on a 2.4 inch ILI9341 color screen, drawn from a framebuffer in RAM. The circuit is an ESP32-C3 with the screen on four SPI wires (GPIO 18 to 21). The boss adds an MPU6050 motion sensor on I2C (GPIO 0 and 1).

Every lesson opens a working sketch that first works out a test case on its own (a fall, an orbit, a head-on hit, a spring's period) and prints the result beside the textbook answer, then runs a live simulation. You change a constant and run again. The checks read the serial output, so every number a lesson quotes is one the board really printed.

The lessons

  1. Vectors and time steps: a Vec2 type with real C++ operators, moving a probe in fixed steps, and a fixed time step loop that keeps physics on its own clock however long a frame takes to draw.
  2. Integration: a dropped ball stepped two ways, explicit Euler against semi-implicit Euler, and two moons in orbit: one spirals out gaining 17.67 percent energy in a single orbit, the other holds its circle.
  3. Collisions: overlap tests, push-apart, impulses along the normal, momentum kept exactly, energy kept or lost with restitution, and a field of six asteroids.
  4. Springs: Hooke's law and a damper, a period measured to the millisecond against 2 pi sqrt(m / k), critical damping, and a tether of eight masses swinging from a space station.
  5. Friction: a crate sliding to a stop (and the bug where friction pushes it backward), the angle where static friction lets go, and a crate riding the deck of a ship rolling in a swell.
  6. Rigid bodies: moment of inertia, torque from an off-center kick, and a solar panel tumbling onto a deck with contact and friction impulses at its corners.

The boss: a tilt-driven sandbox

The last lesson wires an MPU6050 to the board. Its accelerometer reads gravity in the board's own axes, and those two numbers become the pull on a tray of marbles: tip the sensor and they roll downhill, at 5/7 of the sliding rate because a rolling ball has to spin up too. Every step integrates, drags, resolves every pair of marbles and bounces off the walls. You tip it by dragging the sensor in the editor, watch all eight marbles settle on the low side, then fill the tray with more.

What the ESP32-C3 does differently

  • It has no floating-point unit, so every float is done in software. The engine still runs 250 steps a second for twelve marbles, but it is a good reason to keep the inner loops short.
  • The screen is bit-banged SPI and a full frame takes about 37 ms, so physics and drawing run at different rates. That is exactly what the fixed time step in lesson 1 is for.
  • The MPU6050 powers up asleep. The boss writes one register to wake it, then reads four bytes of acceleration in one burst, 16,384 counts to the g.
  • The sketches run on Mokxi's own C3 runtime, with sqrtf, sinf, cosf and atanf from its math library and millis() and micros() for timing.

After this course

Computer graphics from scratch builds the framebuffer, lines, circles and 3D wireframes that these simulations draw with.