The Inventor's Secret

The Inventor's Secret brings Renaissance engineering to life through interactive 3D machines you can explore, operate, and understand.

Comment

💡 Inspiration

For centuries, the pinnacle inventions of classical mechanical engineering—such as Zhang Heng’s 132 CE directional seismoscope and Su Song’s 1092 CE water-regulated astronomical clock tower—have been trapped in cryptic historical woodcuts or static glass museum replicas.

When modern visitors encounter these machines in traditional virtual exhibits, they are almost always trapped in the "Turntable Trap": passive 3D models with text popups where the user can only spin the camera. You cannot test the physics. You cannot watch how force actually transfers through the escapements. And you cannot verify whether the model is historically faithful or a modern CGI fiction.

We asked ourselves: What if an online museum treated historical engineering as code and verifiable physics? What if visitors could turn the gears, inject seismic shockwaves, compare rival academic theories side-by-side, and interrogate an AI docent that never hallucinates?

That vision became The Inventor’s Secret.

⚙️ What It Does

The Inventor’s Secret is a physically simulated, mathematically verified 3D museum of operable classical Chinese mechanical computers, running 100% in modern browsers with zero external database dependencies.

The exhibition features four landmark mechanical computers:

  1. Water-Powered Astronomical Clock Tower (水运仪象台, 1092 CE): Engineered by Su Song and Han Gonglian, this 7-meter pagoda housed the world’s first mechanical escapement. It converts a continuous stream of water into discrete, uniform mechanical heartbeats, driving a celestial armillary sphere and a 5-tier timekeeping chime pagoda.
  2. Zhang Heng’s Directional Seismoscope (候风地动仪, 132 CE): The world’s first earthquake detector. An internal inverted column in high-sensitivity monostable equilibrium senses horizontal seismic shockwaves, tripping an internal crank-and-claw mechanism that drops a bronze ball from a dragon's mouth into a toad, while locking the other seven dragons to prevent echo triggers.
  3. Odometer Drum Carriage (记里鼓车, 1027 CE): A mechanical distance-calculating computer documented by Lu Daolong. As the carriage rolls, an 8-gear decimal reduction train drives automated wooden figurines: striking a drum every 1 Li (561 meters) and a bronze chime every 10 Li.
  4. Laoguanshan Pattern Loom (老官山提花机, 2nd Century BCE): Excavated in 2013 from Tomb M2 in Chengdu, this machine is the ancient ancestor of computer programming. Four foot pedals trigger multi-shaft linkages that mechanically raise pre-programmed combinations of silk warp threads, automating complex jacquard weaving centuries before Western drawlooms.

🔬 "Data is Law": Three-Tier Provenance Engine

Instead of presenting speculative reconstructions as undisputed gospel, our system enforces a strict Three-Tier Archaeological Provenance Architecture:

  • 📜 wenxian (Textual Evidence): Dimensions, tooth counts, and kinematics explicitly cited from primary historical treatises (Xinyi Xiangfayao, Song Shi, Hou Han Shu).
  • 🏺 wenwu (Excavated Relics): Physical coordinates and envelopes measured directly from excavated artifacts (e.g., the preserved scale looms from Chengdu Tomb M2).
  • 📐 tuice (Scholarly Deduction): Explicitly labeled modern academic deductions where dynastic texts are silent, allowing users to toggle between competing reconstructions (such as Wang Zhenduo's 1951 model vs. Feng Rui's 2005 seismoscope model) in a single click.

🛠️ How We Built It

The entire platform is built from the ground up using React 19, TypeScript (Strict Mode), Vite 6, Three.js / React Three Fiber, Zustand, and Groq:

1. Parametric Involute Gear Mathematics

We rejected pre-baked static meshes. Every gear tooth profile, pitch diameter, addendum, dedendum, and root fillet arc is generated algorithmically in code using analytical involute curve geometry:

$$x(t) = r_b (\cos t + t \sin t), \quad y(t) = r_b (\sin t - t \cos t)$$

where ( r_b = \frac{m \cdot z}{2} \cos(\alpha) ) is the base radius derived from historical tooth counts ( z ), module ( m ), and pressure angle ( \alpha ).

2. Verified Decimal Kinematic Transmission

For the Odometer Carriage, the compound transmission ratio was verified using Lu Daolong’s exact 1027 CE tooth counts:

$$\text{Ratio}_{1\text{ Li}} = \frac{54}{18} \times \frac{100}{3} = 3 \times 33.\overline{3} = 100$$

$$\text{Ratio}_{10\text{ Li}} = 100 \times \frac{100}{10} = 1,000$$

Every 100 wheel rotations trip the 1-Li drum mallet; every 1,000 rotations trip the 10-Li chime gong.

3. Automated Spatial Validation & The Poison Gate

To mathematically prove the physical validity of our reconstructions:

  • We integrated three-mesh-bvh (Bounding Volume Hierarchies) to sweep thousands of mechanical states and detect illegal collisions or interpenetrations.
  • We built an automated Poison Gate (pnpm poison): a negative-control test suite that intentionally injects corrupted gear ratios, reversed directions, and missing provenance into the pipeline to mathematically prove that our validator catches every physical flaw.

4. Grounded AI Docent (Groq Llama 3.3 70B)

Unlike generic chatbots that hallucinate ancient history, our AI Docent is strictly constrained to the primary dynastic source records and telemetry of the active 3D model. Every factual claim returns clickable citation chips ([来源:source_id]) that highlight the exact part in the 3D viewer. If an ancient specification is unrecorded, it explicitly admits it rather than inventing numbers.

🧗 Challenges We Faced

  1. Reconciling Cryptic Dynastic Metrology: Ancient Chinese units varied across dynasties (Han chi = 0.231m vs. Song chi = 0.312m). We had to build a centralized metrological conversion engine (src/core/units.ts) to ensure archaeological dimensions mapped accurately into metric SI coordinates.
  2. Dynamic Involute Meshing at 60 FPS: Generating true mathematical involute gears with realistic root fillets in real-time can be computationally heavy. We implemented a unified BufferGeometry merging pipeline that disposes of temporary meshes immediately after creation, keeping memory usage minimal and rendering silky smooth even on mobile devices.
  3. Handling Historical Disagreements: Historians often fiercely dispute missing components. Instead of taking sides, we architected the system with dynamic scheme patches, allowing the visitor to swap between rival scholarly schemes on the fly.

🏆 Accomplishments We're Proud Of

  • 268 Automated Tests Passing: A comprehensive Vitest suite covering unit logic, i18n catalogs, dynamic kinematics, and physical spatial validation.
  • Zero Pre-Baked 3D Files: Over 90% of all moving mechanical parts are procedural buffer geometries generated from pure mathematical equations and archaeological schemas.
  • Zero External Dependencies: The entire experience runs client-side at 60 FPS with instant route switching and offline-ready performance.
  • Strict ≤ 300KB Asset Budget: Fully optimized site assets and audio/visual media adhering to strict lightweight edge delivery rules.

📚 What We Learned

We learned that ancient mechanical computers were not quaint artistic toys—they were rigorous mathematical state machines. Su Song’s escapement solved continuous time quantization two centuries before Europe; Zhang Heng’s seismoscope embodied directional logic gating; and Lu Daolong’s carriage was an autonomous decimal trip computer. Treating ancient engineering with the rigor of modern software development brings cultural heritage to life like never before.

🚀 What's Next for The Inventor's Secret

  • Museum Kiosk Mode: Developing a turnkey, touch-screen terminal build for science and history museums.
  • WebXR / Spatial Computing: Bringing the 1:1 scale Astronomical Clock Tower into VR/AR headsets (Apple Vision Pro & Meta Quest) so visitors can physically walk inside the timber tower.
  • Expansion of the Machine Corpus: Modeling the South-Pointing Chariot (Zhinan Che differential gear train) and Zhang Heng’s Water-Powered Armillary Sphere.

Built With

  • 3d-graphics
  • bvh
  • digital-humanities
  • edge-computing
  • educational-technology
  • groq
  • history-of-science
  • i18next
  • llama-3.3
  • mathematical-modeling
  • open-source
  • physics-simulation
  • playwright
  • react
  • react-three-fiber
  • stem
  • three.js
  • typescript
  • vite
  • vitest
  • web-audio
  • webgl
  • zustand
Share this project:

Updates

Submission history