How my Glider 4.0 port used an oracle
In October I published a browser port of John Calhoun’s 1991 Macintosh game Glider 4.0. The port was directed by a human, implemented by Claude Opus 5.5, and designed by both. You can browser the source and see some screenshots on GitHub or play it in your browser right now. This page documents the porting process and a key technique.
The port achieved its level of fidelity by using an oracle, a black box to test against that gives you the right answer for any input. (Programmers may know this idea as “differential testing” or “golden-master testing”. “Black-box testing” is related.) Here, the oracle is the original Glider running on an emulated Mac. The idea was singled out by Claude Opus 5.5 at the planning stage as the most important idea in the notes on porting Starlark to Python, where a corpus of conformance tests played this role. While Glider came without tests of its own and the Mac’s system software had no pixel-level specification, the original game still ran, so it could act as its own specification.
The oracle is Glider 4.06 (the release nearest the ported 4.05 source, with 4.05’s code used where the two differ) on a modified headless, deterministic Mini vMac, an emulator of the Mac Plus and the Mac II. The emulator runs only in development. No Mac ROMs or System software are present in this repository or on the page.
Every test case is a script of key presses and mouse events, moves and clicks, at given ticks. (A tick is a sixtieth of a second, the Mac’s clock.) The oracle plays the script on the original and records the screen and the sound. The port plays the same script and must match the original exactly: every pixel of every screenshot and the sound tick by tick. When they differ, data is gathered from the original before the port is changed. This means gathering traces of when the Mac registered each key, which Toolbox routines the program called, and what was in memory.
Each behavior the port has beyond John Calhoun’s source is documented in a comment saying how it was measured in the oracle.