Mechanica — A Digital Museum of Ancient Chinese Machines

Inspiration

Almost two thousand years ago, Zhang Heng built a machine that could detect an earthquake hundreds of miles away. For generations, Chinese schoolchildren have learned about it in history class—but no one alive has ever watched the original machine work. The device is long gone. All that survives is a description only a few hundred characters long.

History is full of machines like this. Ancient Greece had the Antikythera mechanism, recovered from the bottom of the sea as a corroded mass of bronze. The Islamic Golden Age had al-Jazari’s water-raising machines, preserved primarily in manuscript illustrations. Song-dynasty China had Su Song’s eleven-meter astronomical clock tower, carried off after the capital fell and never made to run again.

Reading about these machines is not the same as watching them work.

Most museum reconstructions represent a single scholar’s interpretation, frozen in bronze and displayed motionless behind glass—which is exactly the wrong way to encounter a machine. We wanted to see the water fill the scoop, the fork yield, and the wheel advance by one cell.

We wanted to see them in action.

What it does

Mechanica is a museum of machines rebuilt from language and sketches.

Each exhibit begins as a few hundred characters of classical text and becomes a complete 3D mechanism. Every part is dimensioned using versioned data with a cited source, and every movement is driven by simulated physics rather than keyframed animation.

The machines actually run. Pour the water. Arm the gate. Drag the drive handle.

Visitors can pull a machine apart piece by piece, zoom in on a single pivot, and select any component to see its dimensions and the source behind every value: a classical text, a measured artifact, or a clearly labeled inference where scholars had to make an educated guess.

The opening collection contains four machines:

Water-Powered Astronomical Clock Tower · 水运仪象台 Designed by Su Song and his engineer Han Gonglian and completed in 1092 in the Song capital. The eleven-meter tower used falling water to drive an armillary sphere, a celestial globe, and time-announcing figures. Assemble it part by part, then let the water take over. Its escapement divides continuous flow into equal beats—the ancestor of the mechanism ticking inside every mechanical watch.
Seismoscope · 候风地动仪 Built by Zhang Heng in 132 AD in Luoyang. A bronze vessel is ringed by eight dragons. When a distant earthquake arrives, exactly one dragon drops its ball in the direction of the quake while the other seven lock. Arguably the world’s first earthquake instrument, it appears in Mechanica as two rival reconstructions: Wang Zhenduo’s 1951 design and Feng Rui’s 2005 interpretation. One click swaps the internal mechanism. Arm the east gate, inject a pulse, and watch the east dragon fire.
Odometer Drum Carriage · 记里鼓车 A Han-dynasty invention whose complete gear counts survive in Lu Daolong’s 1027 specification. The carriage measures distance as it rolls: two decimal gear reductions translate wheel rotations into a wooden figure’s drumbeat every li and a chime every ten li. It uses the same principle as the odometer in a modern car, executed in wood a millennium earlier.
Pattern Loom · 老官山提花机 Built by unnamed Han weavers around the second century BC and known through loom models excavated in 2013 from the Laoguanshan tombs in Chengdu. The loom stores a textile pattern as a mechanical program within its heddle-lift sequence, weaving the design row by row. It is a programmable machine created roughly nineteen centuries before Jacquard’s punch cards—the same type of cards later used by early computers.

Visitors can also explore a living exhibition stage. On the home page, the machines rotate slowly beneath a fixed museum spotlight, entering the light one at a time.

How we built it

Every line of code was written by OpenAI Codex.

We planned the architecture, reviewed the work, and made the decisions; Codex typed the code. One long-lived session orchestrated the full build, and that session’s ID is included with this submission.

On the final day, three Codex sessions ran in parallel across separate git worktrees. Their work followed a 28-task QA plan with strict file ownership, isolated checkpoints, and controlled merges.

The project’s house rule is simple:

Data is law.

Machine dimensions live in versioned JSON files, with a source attached to every value. Application code is never allowed to invent a number.

The final build passed:

267 unit tests
67 Playwright browser scenarios
A custom geometry-validation suite

Challenges

Rebuilding machines nobody alive has seen

No complete drawings survive.

The available dimensions come from a few hundred characters of Song-dynasty text, Han tomb artifacts, and modern papers whose authors often disagree. To represent that uncertainty honestly, every value in the data model includes both its source and its epistemic status:

Text-attested
Artifact-measured
Scholar-inferred

When scholars disagree, the museum presents multiple reconstructions rather than pretending that one interpretation is certain.

Making the simulation honest

Su Song’s escapement is a self-regulating feedback loop:

The scoop fills.
The fork yields.
The gate opens.
The wheel advances exactly one cell.
The mechanism locks again.

That behavior must emerge from the mechanism’s simulated state. It cannot be a keyframed animation; otherwise, a “working reconstruction” would be theater.

The seismoscope follows the same standard. Its first-event interlock must ensure that one dragon fires, the other seven lock, and only the armed direction can trigger.

Proving the geometry

The clock tower alone contains 87 interlocking parts.

A custom validator sweeps every mechanism through its complete motion cycle at half-degree resolution. Each run performs roughly 4,000 checks covering:

Part collisions
Gear meshing
Motion envelopes
Mechanical clearances

Codex also wrote poison tests that deliberately corrupt the data—for example, by inserting an incorrect gear ratio or deleting a required source—to prove that the validator detects genuine failures.

In that suite, a green result would be the bug.

All four poisons were caught.

Keeping the AI honest

The docent may never state a number that the museum’s corpus cannot support.

That constraint runs through the entire stack:

Per-value sources in the JSON
A prompt contract that forbids unsupported dimensional arithmetic
Citation chips embedded in streamed responses
A refusal path tested like any other product feature

Most chatbot demos showcase confidence.

Ours showcases restraint.

Solving the ordinary kind of hard

Not every challenge was historical or theoretical.

An idle auto-pause silently stopped demonstrations after three seconds. We discovered it by clicking through the museum like a bored visitor rather than following the intended path.

Later, at 9 p.m. on the night before submission, the serverless runtime began returning 500 errors because of bare JSON imports.

Both issues became part of the final QA process.

What’s next

The museum was designed to grow.

Its provenance schema is deliberately culture-agnostic. A dimension sourced from Vitruvius or al-Jazari’s 1206 manuscript receives the same three-way classification as a dimension taken from a Song-dynasty treatise:

Text-attested
Artifact-measured
Scholar-inferred

The validator does not care which language the historical argument was written in.

The roadmap is therefore simple:

More wings. Same law.

The next machine: the South-Pointing Chariot · 指南车

The South-Pointing Chariot carries a wooden figure that continues pointing south regardless of how the carriage turns.

Its gear counts survive in Song court records, much like those of the odometer. Whether those gears constitute a true differential remains the subject of scholarly debate—exactly the kind of disagreement this museum was built to stage.

The first wings beyond China

Future exhibits could include:

The Antikythera mechanism, whose rival reconstructions have become a scholarly genre of their own
Al-Jazari’s water-raising machines
Hero of Alexandria’s automata

Each exhibit would follow the same architecture: the same JSON schema, the same validator, and the same rule that code may never invent a number.

A docent that can leave the building

A future citation-allowlisted web mode would allow the docent to search beyond the museum’s internal corpus—but only within pre-vetted scholarly sources.

Every claim would still require a pinned citation.

Classroom mode

Guided tours could help teachers use the machines as lessons:

Run the escapement as a physics demonstration.
Explore the gears as a mechanical-engineering exercise.
Use provenance labels to teach a more difficult lesson: the difference between what we know and what we infer.