FERRETGame engine over Babylon.js
Ferret

Liquids

Skill ferret-physics-liquids · download all skills · SKILL.md

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.