---
name: ferret-physics-recipes
description: Use to turn a physics wish into Ferret capabilities and a worked recipe: "make the bridge break", "boil a pot", "flood a cellar", "a tank that explodes in a fire". Maps wishes to the capability skills and carries the whole cookbook and the scenarios.
---

# From a wish to the right capabilities

## When to use
You know what should happen in the game, not which package does it.

## Wish to capability

| Wish | Capabilities | Skill |
|---|---|---|
| Low gravity, a planet, water drag, wind | gravity, media | `ferret-physics-gravity-media` |
| Ice, grip, things that settle, sticky things | friction, impact | `ferret-physics-friction-impact` |
| Things that break, walls in pieces | strength | `ferret-physics-strength` |
| Ropes, springs, cloth, jelly | stretch | `ferret-physics-stretch` |
| Fire, boiling, heat, steel that weakens | heat | `ferret-physics-heat` |
| Guns, engines, rockets, boilers, blasts, craters | combustion, explosions | `ferret-physics-combustion-explosions` |
| Tanks, pipes, lakes, waves, wings | liquids | `ferret-physics-liquids` |
| Digging, slumping, mud, tunnels | terrain | `ferret-physics-terrain` |
| Circuits, lamps, motors, fuses | electric | `ferret-physics-electric` |
| Reactions, radiation, reactors | chemistry, nuclear | `ferret-physics-chemistry-nuclear` |
| Gears, drivetrains, turbines | mechanisms | `ferret-physics-mechanisms` |
| Boats, submarines, balloons | vehicles | `ferret-physics-vehicles` |
| One thing driving another (fire heats a pot, steam turns a turbine) | links | `ferret-physics-links` |

## Steps
1. Find the closest recipe in `recipes/` (cookbook pages by theme, scenarios for whole chains).
2. Read the capability skill named above for the switch-on steps and the failure table.
3. Register and enable only what the level needs (`ferret-physics-host`); set values at the narrowest scope.
4. Copy the numbers into a test in the fixed-step world; assert against a law, not against a value seen once.
5. Measure the step time and set the tier (`ferret-physics-fx-tuning`).

## Check afterwards
The recipe's expected outcome appears in a headless run; the energy or mass balance closes where the guide says it should.

## What usually goes wrong
- A capability used without being enabled (`physics.info` shows what is on).
- Reaching for one package when the effect is a chain: use links, not special code.
- Large numbers copied from a recipe into a different unit system: everything is metres, kilograms, seconds, kelvin.

## Files

- `reference/overview.md` — Realism as capabilities a game switches on, the host and kernels, scoped values, the fixed phases, budgets and tiers.
- `reference/capabilities.md` — Every physics capability: the package, its registered name, its phase and what it adds.
- `recipes/fire-and-heat.md` — Eight recipes: boil a pot, a beam in a fire, a pressure cooker, a kettle on a breaker, a cold pack, thermal runaway, an overloaded wire, a glowing brake disc.
- `recipes/structures-and-ropes.md` — Six recipes: a rope that holds a load or snaps, a shear pin that protects the rest, a crate that breaks only at speed, a bungee that springs back, a wall that breaks under a blast, a curtain that hangs.
- `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/blasts-and-ground.md` — Seven recipes: danger rings, a crater in sand and in rock, a charge buried too deep, a crater in a real terrain, a wall that shields, an underwater burst, a trench that holds or slumps.
- `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.
- `recipes/reactions-and-radiation.md` — Six recipes: how much lead, a hot patch that fades and washes, a reactor without cooling, equilibrium shifted by squeezing, a rocket that gains with altitude, a barrel that bursts.
- `recipes/boiler-house.md` — A fire heats a boiler, steam drives an engine, a generator on the shaft lights a lamp. Four capabilities, three links, one energy account that must add up.
- `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.
- `recipes/loss-of-coolant.md` — A reactor runs a turbine, a generator and a lamp. The coolant pump stops; the lamp dies, the trip scrams the core, and decay heat warms the containment.
- `recipes/progressive-collapse.md` — Two parallel hangers share a load. When the weaker one goes the stronger one inherits all of it and fails too: progressive collapse, with redundancy as the cure.
- `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/tuning.md` — Where the cost of the capabilities goes and which knob buys it back: sub-steps, step rates, off-screen sleep, and what to switch off first.