---
name: ferret-physics-liquids
description: Use for liquids in Ferret: tanks and pipes, height-field water (waves, boats), particle liquids (splashes), foil lift and Magnus force, capillarity and wicks, and hydraulics (jacks, rams, valves, accumulators).
---

# Liquids

## When to use
A cellar that floods, a harbour with waves, a splash, a wing, a spinning ball.

## Which tool
- **Reservoirs and pipes** (`LiquidNetwork`): pressure by depth, communicating vessels, orifices, pumps, check valves, `main` supplies. Cheapest.
- **Water surface** (`WaterSurface`, `waterSurface`): shallow-water waves at `√(g h)`, currents, boats that push it.
- **Particles** (`Fluid`, `particleLiquid`): splashes, viscosity, surface tension; the most expensive, with a `budget`.
- **Hydraulics** (`HydraulicCircuit`, `hydraulics()` capability, level block `physics.hydraulics`): compressible lines, cylinders, pumps, directional and relief valves, accumulators; drive with `(spool …)`.
- **Foils and spin** (`thinFoil`, `foilForce`, `magnus`): lift and stall, curving balls.

## Steps
1. Enable `liquids` (network), `surface` or `fluid` as needed.
2. Network: `addReservoir({ id, liquid, container, level })`, `addLink({ id, from, to, fromElevation, toElevation, diameter, length })`; `'air'` is the other end.
3. Step at 10–20 Hz; open edges on waves fade them, walls reflect.
4. Particles: keep counts under the budget; bodies join by shape.
5. Commands: `liquid.add`, `reservoir.add|state`, `surface.disturb|height`, `capillary.add`.

## Check afterwards
Two tanks settle at the mean level; mass is conserved; waves slow on shallow water.

## What usually goes wrong
- A tank never empties: orifice tiny for the head, or units in centimetres.
- Water runs uphill: a pump on the link, or elevations are not world heights.
- `reservoir "x" not found`: link ends name reservoir ids.
- Waves blow up: step over the stability limit; use a smaller step or larger `dx`.
- Particles over budget halve their work.

## Hydraulics
- A closed valve locks a cylinder (oil is a stiff spring); a relief valve is what limits the pressure at an end stop, so always fit one.
- A cylinder bound to bodies (`attach`) has `mass` 0 or omitted: the bodies carry the mass.
- A rod as thick as the bore is refused at load; the error names the node.

## Files

- `reference/liquids.md` — Tanks and pipes, lakes and rivers, splashes and pours, and the lift of wings, sails and spinning balls: four tools for liquids at four costs.
- `reference/api-physics-liquids.md` — every export of `@ferret/physics-liquids` with signature and doc comment
- `reference/commands.md` — 20 commands of these packages with their arguments
- `recipes/water-and-boats.md` — Six recipes: tanks that equalise, a U-tube of two liquids, a wave that slows on a beach, a boat that sinks deeper with cargo, a wing that stalls, a ball that curves.
- `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.