Simulating a Clockwork Automaton in Matter.js

This guide explains how to design and simulate a functional mechanical clockwork automaton powered by spring motors using the Matter.js 2D physics engine. You will learn how to create a regulated energy source through virtual coiled springs, design an escapement mechanism to prevent uncontrolled unwinding, transmit power through gear trains, and convert rotational motion into lifelike automaton movements using mechanical linkages.

1. Simulating the Spring Motor (Mainspring)

Matter.js does not provide a native spiral torsion spring, but you can simulate a mainspring's energy storage and torque release mathematically or physically:

• Algorithmic Torque Application: The most stable way to model a wound spring is to apply continuous rotational force directly to the main arbor (drive wheel). Using the beforeUpdate engine event, modify the drive body's torque property based on Hooke's Law for torsion (\(\tau = -\kappa \theta\)), where stored angular displacement drains as the drive wheel rotates.
• Physical Constraint Arrays: Alternatively, anchor multiple linear Matter.Constraint instances tangentially from a static casing to pins on a central wheel. Staggering these elastic constraints provides cyclical tension that mimics a wound coil.

Matter.Events.on(engine, 'beforeUpdate', () => {
    if (storedSpringWind > 0) {
        mainArbor.torque = springConstant * (storedSpringWind / maxWind);
        storedSpringWind -= mainArbor.angularVelocity * dampingFactor;
    }
});

2. Building the Escapement Mechanism

Without an escapement, a spring motor discharges instantly in a rapid spin. An escapement meters energy delivery in precise ticks.

1. Escape Wheel: Construct a rigid star-shaped body using Matter.Bodies.fromVertices with ratchet-style asymmetrical teeth. Pin its center to the world using a rigid constraint (stiffness: 1, length: 0).
2. Pallet Fork (Anchor): Create a curved lever with two pallet arms positioned above the escape wheel. Pin its center with another rotational constraint.
3. Oscillator (Balance Wheel or Pendulum): Attach a pendulum mass or a wheel stabilized by a bi-directional spring constraint.
4. Action: As the mainspring turns the escape wheel, a tooth pushes against a pallet stone, impulses the oscillator, and locks against the opposite pallet. The return oscillation frees the tooth, advancing the wheel by one increment.

3. Constructing the Gear Train

Power must be stepped down or up to drive different parts of the automaton:

• Physical Interlocking Teeth: Create realistic cogs using Matter.Bodies.fromVertices with trapezoidal teeth. To prevent gear slippage, increase engine.positionIterations and engine.velocityIterations to at least 10 or 12. Set friction high (0.8 to 1.0) and restitution to 0.
• Constraint-Linked Gears (Higher Performance): For better performance and zero risk of tooth jamming, use smooth circular bodies for the wheels and enforce angular velocity ratios via an update loop:

Matter.Events.on(engine, 'afterUpdate', () => {
    followerGear.angularVelocity = -driverGear.angularVelocity * (driverRadius / followerRadius);
});

4. Designing Automaton Linkages

Clockwork figures move using mechanical linkages driven by cams, cranks, and eccentrics connected to the gear train:

• Cranks and Eccentric Pins: Place a rigid circular pin offset from the center of a driven gear.
• Connecting Rods: Attach a Matter.Constraint to the offset pin on one end and to the automaton's limb (such as an arm or leg) on the other.
• Pivot Joints: Pin limbs to fixed coordinate axes or other mobile segments using non-elastic constraints (stiffness: 1) to form four-bar or Jansen-style walking linkages.
• Cams and Pushrods: Use non-circular composite bodies attached to an axle, resting against a spring-loaded slider constraint to produce intermittent gestures like blinking eyes or nodding heads.

5. Tuning Stability and Performance

Clockwork mechanisms rely on tight clearances and continuous contact, which challenge real-time physics solvers. Apply the following settings to ensure smooth operation:

• Sub-Stepping: Reduce the simulation time step in Matter.Engine.update(engine, 1000 / 120) to calculate 120 Hz intervals rather than standard 60 Hz, preventing fast-moving pallet teeth from tunneling through barriers.
• Zero Restitution: Set restitution: 0 on all gears, pallets, and stops to eliminate unwanted bouncing.
• Collision Filtering: Assign distinct collisionFilter.group and collisionFilter.mask values to ensure gears only collide with their mating pairs and escapement levers, preventing adjacent linkages from snagging on one another.