---
name: ferret-physics-mechanisms
description: Use for rotating machinery in Ferret: Drivetrain of shafts, gears, belts, clutches, brakes, differentials, worm gears, cardan joints, turbines and propellers, flywheels, tooth strength and breaking, and binding a shaft to a body.
---

# Mechanisms and drivetrains

## When to use
A gearbox, a winch that cannot run back, a wind or water turbine, a brake, a flywheel.

## The model
A `Drivetrain` holds **shafts** (inertia `J`, friction `b`) joined by **couplings** (gear, belt, clutch, differential, worm, cardan). Nothing is free: each mesh passes on part of the torque, the rest is heat, and the network keeps the account. Drivers push torque, loads take it. A gear with a `limit` or a shaft with `diameter` and `shear` breaks (`machine:break { element, torque }`).

## Steps
1. `d.shaft({ name, J, b })`, couple them (`d.worm(...)`, `d.brake(...)`), drive with `d.drive(shaft, torqueFn)`.
2. Turbines and propellers: `windTurbine`, `waterTurbine`, `propeller` with `cpCurve`.
3. Step: `d.step(dt, substeps)`; tie to a scene body with `bind` (kinematic) or `couple` (dynamic).
4. A worm whose lead angle satisfies `tan λ < μ` is self-locking.
5. Commands: `machine.info|set|state|step`.

## Check afterwards
Work by drivers equals what loads took plus losses plus stored spin; a locked worm holds the load; a heavier flywheel ripples less.

## What usually goes wrong
- Output does not move: a brake is on (`command` 1) or the motor drives the wrong shaft.
- A shaft spins up without bound: no load and no friction, give `b`.
- Everything shakes: huge inertia ratio at a coarse step; raise substeps.
- `bind` throws: the body is not kinematic.
- `machine:stall` appears only on shafts that have a driver.

## Files

- `reference/mechanisms.md` — Gearboxes, differentials, clutches, brakes, turbines and propellers: how rotation is carried from a motor to a load, and what makes a part break.
- `reference/api-physics-mechanisms.md` — every export of `@ferret/physics-mechanisms` with signature and doc comment
- `reference/commands.md` — 4 commands of these packages with their arguments
- `recipes/machines-and-circuits.md` — Six recipes: a lamp that surges and burns, a rectifier that smooths, a transformer, a wind turbine lighting a lamp through a generator, a winch that cannot run back, a flywheel that evens out a pulsing drive.