---
name: ferret-physics-links
description: Use to close loops between Ferret physics capabilities with links: fire heats a pot, steam turns a turbine, a generator lights a lamp, a brake heats its drum, with an energy account that must add up. Covers gasInPart, slipHeats, wireFire, arcFlash and your own links.
---

# Links between capabilities

## When to use
One capability's output must be another's input (heat to gas, shaft to lamp, short circuit to blast).

## The model
Each capability stays ignorant of the others; a **link** is a small object that moves a quantity between them and keeps an **energy account** (`EnergyTerm`) that must add up. Ready links: `gasInPart`, `vesselInPart`, `reservoirInPart`, `slipHeats`, `plasticHeats`, `stagnationHeats`, `reactorHeatsPart`, `turbineOnReactor`, `boilerFed`, `engineOnBoiler`, `screwOnShaft`, `coilPulls`, `armatureOf`, `mudOver`, `navFollowsTerrain`, `wireFire`, `arcFlash`.

## Steps
1. Enable `links`; `add` each link to the capability.
2. Give each side the interface the link needs (`HeatPartLike`, `GasLike`, ...).
3. The rule between worlds is your code: `socket.closed = cellar.level > 0.3`; the link moves the numbers.
4. Check `links.energy` (the account) and `link.state`.
5. Write your own by implementing `Link` with its `terms`.

## Check afterwards
The energy total does not drift over a long run; each pair is joined once.

## What usually goes wrong
- Total drifts: a link writes without taking from the other side, or a store is missing from `terms`.
- A link does nothing: not `add`ed, or `links` not enabled.
- Heat appears twice: two links join the same pair.
- A link runs after the capabilities have stepped: what it writes is used next step.

## Files

- `reference/links.md` — Small objects that close loops between capabilities (a fire heats a pot, steam turns a turbine, a generator lights a lamp), with an energy account that must add up.
- `reference/api-physics-links.md` — every export of `@ferret/physics-links` with signature and doc comment
- `reference/commands.md` — 1 commands of these packages with their arguments
- `recipes/tank-fire.md` — A fire heats a sealed tank, the gas inside warms and its pressure climbs, the shell gives way and the tank becomes a blast with fragments that push a crate. Heat, links, gas, explosions and bodies in one loop.
- `recipes/flooded-cellar.md` — A burst main fills a cellar faster than the sump pump can empty it; the water reaches a socket, the circuit shorts, the breaker trips, the pump stops, and the flood wins.