---
name: ferret-physics-engines
description: Use for steam engines (a boiler, a double-acting cylinder with valve gear, a locomotive's two cylinders, reverser, cut-off, governor) and multi-cylinder piston engines (firing order, ignition advance, fuel cut, starter, idle) in Ferret, and for the shaking of an engine on its mounts.
---

# Engines

## When to use
A locomotive or a steam launch, a mill engine with a governor, a car or a motorbike engine that has to start, idle, rev and stall, a generator set on rubber mounts.

## The model
An engine is a torque source on a drivetrain shaft; its torque is the work the gas does over the angle the crank turned. The steam cylinder takes steam from a `Boiler` through a port that opens and closes by crank angle (the valve gear); a multi-cylinder piston engine is several `PistonEngine`s on one crank, shifted by the firing order. The shaft's housing (A0) takes the reaction torque; `applyInertia` puts the reciprocating masses' unbalanced force on the mounts.

## Steps
1. Build the `Boiler` (`physics-combustion`) and a `Drivetrain` with a crank shaft (`physics-mechanisms`; give it a `housing` if the block moves).
2. `new SteamEngine({ bore, crank, rod, boiler, inlet, exhaustPort, phases: [0, Math.PI / 2], gear: { cutoff, lead, release, compression } })` or `new MultiCylinderEngine({ cylinder, count, order })`, then `drivetrain.drive(crank, engine.torque)`.
3. Register the controls for programs: `engineForms(bridge, { engines, boilers })` gives `throttle`, `cutoff`, `reverse`, `ignition`, `fuel`, `engine-rpm`, `pressure`, `level`.
4. Write the governor, the starter and the reverser as programs and bindings.
5. For the shaking, call `engine.applyInertia(omega, theta, mount)` every step with the body or vessel as `mount`.

## Check afterwards
The work per turn is the indicator area for the cut-off; the pressure of the boiler falls as steam is drawn; the four-cylinder torque varies far less than one cylinder's; the primary inertia forces of an inline four cancel.

## What usually goes wrong
- A one-cylinder steam engine sticks on a dead centre: use two cylinders at 90° (`phases`).
- The speed runs away: there is no load, or the governor program does not run (tick the runtime).
- The engine does not start: the port is shut at that crank angle (a cut-off of 0.5 or less can leave a 90° pair with no open port); use a longer cut-off to start.
- A used engine object is reused after the crank angle was reset: an engine remembers the angle of its last call; build a fresh one.

## Files

- `reference/engines.md` — physics/engines.md
- `reference/combustion.md` — Burning in a closed space and using the pressure: guns, rockets, petrol and diesel engines, jets, boilers and gas cylinders that burst.
- `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-engines.md` — every export of `@ferret/physics-engines` with signature and doc comment
- `reference/api-physics-combustion.md` — every export of `@ferret/physics-combustion` with signature and doc comment
- `reference/api-physics-mechanisms.md` — every export of `@ferret/physics-mechanisms` with signature and doc comment
- `reference/api-motion.md` — every export of `@ferret/motion` with signature and doc comment
- `reference/commands.md` — 12 commands of these packages with their arguments