[06]entry 6 of 34
Poltergeist
this entry is written twice, in full
- 1.in brief
2D physics lab on a hand-written Rust engine, in the browser
- 2.in general
A physics lab that lets you pause a collapsing tower and read exactly why it fell.
- 3.in particular
A zero-dependency rigid-body engine in Rust, compiled to WebAssembly: 160 bodies step in about half a millisecond, and ten seconds of full solver state can be rewound and replayed exactly.
- 1.in brief
a physics playground in the browser, with the physics written from scratch
- 2.in general
A physics lab that lets you freeze a falling tower and read exactly why it fell.
- 3.in particular
The physics is hand-written in a fast systems language with nothing borrowed, runs inside the browser, moves 160 objects in about half a thousandth of a second, and can wind ten seconds back and play them again exactly.
context
Poltergeist is a local-first 2D physics lab: a rigid-body engine written from scratch in Rust1, compiled to WebAssembly2, under a Svelte workspace for building mechanisms and watching them fail. No account, no server, no API key and no external font; the simulation and every saved experiment stay on the device. It ships eleven experiments, from a twenty-one-block tower and a domino run to motorised mechanisms and a 160-body stress chamber, and one of them is an empty chamber to build in.
the problem
Most physics demos are a black box that either looks right or does not. A lab has to show its working: where two bodies touch, which way the contact pushes and how hard, where the energy went, and what the moment before looked like. That needs an engine whose internals can be read and whose past can be restored exactly, fast enough that the reading costs nothing, inside a browser tab.
what i built
Two crates with no external dependencies: a headless core and a thin WebAssembly2 layer of plain scalar exports, with no wasm-bindgen and no wasm-pack. The browser decodes one versioned frame of packed floats after each tick or edit, rather than querying a paused world on every animation frame, and IDs are capped at 16,777,215 so a float carries them exactly.
- 1.
A sweep-and-prune broad phase in stable order, circle, box and regular-polygon narrow phases, and separating-axis polygon collisions with clipped contact manifolds
- 2.
Sequential impulses with warm starting, friction clamped by the accumulated normal impulse, a restitution threshold and separate positional correction: two substeps per fixed 60 Hz tick, with bounded catch-up so a stalled frame cannot build a backlog
- 3.
Rods, ropes, damped springs and motorised pins, plus island sleeping with transitive wake-up, so a resting tower costs almost nothing until something hits it
- 4.
Swept-circle collision against fixed scenery, rounded corners included, so a fast ball cannot tunnel through a thin wall
- 5.
A ten-second timeline of full solver checkpoints (contacts, warm-start caches, sleep timers, joints and the clock), with tests proving a rewound run continues exactly as the original did
- 6.
A workspace built to be read: contact normals and impulses in N·s, velocity vectors, trails, a live energy chart with CSV export, rulers, undo, keyboard placement, a 24-slot library, recovery every three seconds and gzip-compressed share links
- 7.
An installable offline build: a service worker pre-caches one coherent version of the shell and the engine, and updates only when asked, after saving a recovery snapshot
outcome
The engine is 173 KB of WebAssembly2 (61 KB gzipped) and steps 160 mixed bodies in about 0.55ms a tick on an M2, against a 16.7ms frame. 36 Rust1 tests cover the physics and the replay, and Playwright8 drives the lab in Chromium, WebKit and a phone viewport, accessibility checks and a real offline reload included. The limits are written down too: only circles get swept protection, and a replay is exact within one build, not across browsers.
A physics engine you can interrogate: pause it, step it backwards, select a body and read the impulse holding it up, then send the whole experiment to someone as a link.
context
Poltergeist is a physics lab that lives entirely on your own computer: the part that works out how solid objects move and collide was written from scratch, and it sits under a workspace for building contraptions and watching them fail. There is no account, no server and nothing fetched from elsewhere; the simulation and every saved experiment stay on the device. It comes with eleven experiments, from a tower of twenty-one blocks and a row of dominoes to motor-driven machines and a chamber holding 160 objects, and one of them is an empty room to build in.
the problem
Most physics demos are a sealed box that either looks right or does not. A lab has to show its working: where two objects touch, which way each pushes the other and how hard, where the energy went, and what the moment before looked like. That needs physics whose insides can be read and whose past can be put back exactly, fast enough that reading it costs nothing, and all of it inside a browser tab.
what i built
Two pieces, neither of which borrows a single line from anyone else: the physics itself, which knows nothing about screens, and a thin layer that lets the browser call it, deliberately without the usual helper tools. After each moment of simulation the page reads one compact, versioned list of numbers describing everything on screen, instead of asking the paused world the same questions sixty times a second, and every object’s number is kept small enough to survive being stored in that list without rounding.
- 1.
A quick first pass that finds which objects might be touching, in a fixed order, then exact tests for circles, boxes and regular polygons that work out precisely where and how deep two shapes meet.
- 2.
The standard method of resolving every touch with small pushes, repeated until they agree, starting each moment from the last one’s answers so stacks stay steady, with grip limited by how hard two surfaces press together, bounce only above a minimum speed, and overlaps nudged apart separately. Each sixtieth of a second is worked through in two halves, and a slow moment can never pile up work the simulation then has to rush through.
- 3.
Rods, ropes, springs that settle and pins that can be driven by a motor, plus groups of resting objects that go to sleep together and all wake the moment one of them is disturbed, so a tower standing still costs almost nothing until something hits it.
- 4.
A fast ball is followed along its whole path rather than checked only where it lands, corners included, so it cannot pass straight through a thin wall between one moment and the next.
- 5.
Ten seconds of history kept in full, down to every point of contact and the leftovers each one carries forward, with tests proving that a rewound run carries on exactly as the original did.
- 6.
A workspace built to be read: arrows for where things touch and how hard, how fast each object is going, the path it took, a live energy chart you can download, rulers, undo, placing objects from the keyboard, room to save 24 experiments, an automatic save every three seconds, and links that pack an entire experiment into the address.
- 7.
It installs like an app and works with no connection: the whole thing is saved on the device as one consistent version, and it only updates when you ask it to, after quietly saving where you were.
outcome
The physics is 173 KB, 61 KB once compressed, and moves 160 mixed objects in about half a thousandth of a second per step on a recent Mac, against the seventeen thousandths a screen gives each frame. Thirty-six automated tests check the physics and the rewinding, and a robot drives the lab through two different browser engines and a phone-sized screen, including accessibility checks and reloading it with the internet switched off. The limits are written down as well: only circles are followed along their path, and a replay is exact on the same version, not across different browsers.
Physics you can question: freeze it, step it backwards, pick one block and read how hard it is being held up, then send the whole experiment to someone as a link.