# Capability catalogue

# Capability catalogue

Each capability lives in its own package, so a game loads only what it registers. The *name* is what `host.enable(name)`, a manifest's `physics.capabilities` and the `physics.*` commands use.

## Bodies

| Package | Name | Phase | What it adds |
|---|---|---|---|
| `physics-gravity` | `gravity` | field | gravity as a field: a uniform vector per scope, point attractors (a planet, a pit) with softening and range, a scale per body. The character reads it too |
| `physics-media` | `media` | field | water, mud, wind and air as media with density and viscosity: drag (linear then quadratic), buoyancy against the true volume below the surface, flow, gusts; the standard atmosphere |
| `physics-friction` | `friction` | strength | friction by scope on top of the materials' own: sliding and rolling, pivot friction, anisotropy. Ice is a material, not a special case |
| `physics-impact` | `impact` | strength | restitution from sticking to perfectly elastic, a rest threshold, energy lost reported as an event |
| `physics-strength` | `strength` | strength | finite strength: impacts damage and break bodies into pieces (capped by the tier's `maxPieces`); links that break over force or torque |
| `physics-stretch` | `stretch` | stretch | springs, ropes and bands (Hooke, damping, rest length, tear at maximum stretch); cloth and soft bodies by position-based dynamics |

## The ground, blasts, heat and matter

| Package | Name | What it adds |
|---|---|---|
| `physics-terrain` | `terrain` | a layered soil height field that can be dug, filled, slumps to its angle of repose and floods; sinkage of loaded bodies; tunnels; terrain as meshes for the kernel |
| `physics-explosions` | `explosion` | a blast from an energy: overpressure and impulse by scaled distance, shielding, fragments and spall, craters |
| `physics-heat` | `heat` | temperature of parts, heat capacity, conduction, convection, radiation, phase change, expansion, melting and loss of strength |
| `physics-chemistry` | `chemistry` | reactions with rate laws (Arrhenius) in well-stirred vessels, heat of reaction, pressure, venting |
| `physics-nuclear` | `nuclear` | decay and chains, activation, radiation dose and shielding along a ray, reactor kinetics with rods and scram, fallout |
| `physics-combustion` | `combustion` | combustion chambers, guns, rockets, piston engines, steam boilers, jets: burning raises temperature and pressure, flow through nozzles |

## Machines and vehicles

| Package | Name | What it adds |
|---|---|---|
| `physics-electric` | `electric` | circuits of sources, wires, resistors, lamps, motors, inductors, capacitors, relays and potentiometers, solved each step |
| `physics-mechanisms` | `machine` | drivetrains of shafts and couplings, gears, belts, clutches, brakes, turbines, cardan joints, tooth strength |
| `physics-vehicles` | `vehicles` | ships, submarines, balloons: hulls, ballast, flooding, thrusters, foils and sails |
| `physics-liquids` | `liquids`, `surface`, `fluid` | three models of growing cost: containers and reservoirs (pressure by depth, communicating vessels), a height-field water surface (waves, currents, boats that push it), particles (splashes, viscosity, surface tension, capillarity) |

## Glue and look

| Package | Name | What it adds |
|---|---|---|
| `physics-links` | `links` | closes loops between capabilities, see Linking capabilities (skill `ferret-physics-links`) |
| `physics-fx` | none | the render side: glow of hot parts (blackbody colour), water meshes, fluid views, lamp lights. It reads state and never changes it |
| `physics-havok` | none | the loader for Havok's WASM |

## Dependencies are data

Strength and stretch use a material's strengths; friction and impact use its friction and restitution; media uses a body's density and extent; liquids use a liquid's density, viscosity, surface tension and contact angle; gravity uses nothing. A capability that needs another declares it in `requires`.

Every API item of a capability is on its package page; every capability also registers commands (`gravity.set`, `heat.add`, `circuit.add`, `terrain.dig`, ...), listed in Commands (skill `ferret`).

## The packages of the dynamics plan as libraries (stage M)

`npm run libs` (`tools/code-lib/build.mjs`) packs `motion`, `flow`, `physics-actuators`, `physics-rotor`, `physics-engines`, `flow-solver` and `physics-pneumatics` as `.ferret` libraries (`dist/lib/ferret-libs/<id>-<version>.ferret`). A library is the package's `src/library.ts` as one ES module: its own code, with the rest of the engine read from the shared `Ferret` (`ctx.ferret`), and `install(ctx)` registers its capability or service (`actuators`, `rotors`, `flowbox`, `pneumatics`, the `flow` service). The manifest lists `dependencies` (the code loader runs them first) and `provides` (capabilities, kinds, flow sources, forms, commands, level keys) so a level or a program is resolved to libraries without running them. Libraries are built unsigned; signing is done with the owner's key at release.