# @ferret/physics-links: API Links that close loops between capabilities: a fire heats a pot, steam turns a turbine, a generator lights a lamp. Links between capabilities: the places where one capability's output is another's input, so a world closes its loops (a fire heats a pot, steam turns a turbine, the turbine a generator, the generator lights a lamp; a screw pushes a ship and loads its engine). Each capability stays ignorant of the others; a link is a small object that reads one side and writes the other once a step, after the capabilities have stepped, and keeps the energy it moves so a scene can account for it. The link reads and writes through the plain fields and methods of the objects it joins (a heat part, a chemical vessel, a gas volume, a shaft, a reactor, a thruster, a kernel body), so this package imports none of their packages. 36 exports. Generated from the source (`packages/physics-links/src`), so it matches the code. ## Functions ### arcFlash *function* · `packages/physics-links/src/index.ts:228` ```ts function arcFlash(world: WorldLike, o: { circuit: string; at: Vec3; voltage: number; arcVoltage?: number; blastShare?: number; maxTime?: number; detonate: (d: { at: Vec3; energy: number; burst: 'air' }) => unknown }): Link & { dispose(): void } ``` An arc fault: from the first `circuit:short` until the circuit is cleared (`circuit:trip` or `circuit:blown`, or `maxTime`), the arc dissipates V_arc · I · t; a share of that goes into a blast at `at` (the rest is light and heat), handed to X as joules. One blast per fault. ### armatureOf *function* · `packages/physics-links/src/index.ts:138` ```ts function armatureOf(coil: { gap: number; force: number }, body: Body, pole: Vec3, kernel: KernelLike, reach = 0): Link ``` A coil element (W's `Coil`) and an armature body: the gap follows the distance of the body from the pole, the coil's pull acts on the body along the line to the pole, and the work it does is counted (the coil's own energy account takes the other side). Plain fields only: `gap` is written, `force` is read. ### boilerFed *function* · `packages/physics-links/src/index.ts:400` ```ts function boilerFed(boiler: FeedableBoiler, tank: { volume: number }, o: { setpoint: number; rate: number; density?: number; T?: () => number }): Link & { fed: number } ``` A feed pump between an L1 reservoir and a boiler: while the drum holds less water than `setpoint` (kg), it moves at most `rate` m³/s of the tank's liquid into it, never more than the tank has and never past the setpoint, at the tank's temperature `T` (the boiler cools by exactly what the cold water costs to heat). An empty tank starves the boiler. ### coilPulls *function* · `packages/physics-links/src/index.ts:152` ```ts function coilPulls(current: () => number, body: Body, pole: Vec3, kernel: KernelLike, force: (I: number, gap: number) => number, reach = 0): Link ``` ### engineOnBoiler *function* · `packages/physics-links/src/index.ts:99` ```ts function engineOnBoiler(boiler: BoilerLike, shaft: ShaftLike, o: { area: number; exhaust: number; work: (p1: number, p2: number) => number; maxTorque: number; throttle?: () => number }): Link ``` A steam engine or turbine on a boiler: steam flows through the throttle (`throttle()` 0..1 of `area`) to the exhaust pressure, the boiler loses it with its enthalpy, and `work(p1, p2)` per kilogram (K's `steamWork`) turns the shaft, as power / ω. ### gasInPart *function* · `packages/physics-links/src/index.ts:58` ```ts function gasInPart(gas: GasLike, part: HeatPartLike, net: HeatNetLike, G: number, at: 'volume' | 'pressure' = 'volume'): Link ``` A gas volume and a heat part exchange heat through a conductance G (W/K): a hot wall warms a tank's gas and raises its pressure. ### links *function* · `packages/physics-links/src/index.ts:179` ```ts function links(): LinksCapability ``` ### mudOver *function* · `packages/physics-links/src/index.ts:332` ```ts function mudOver(terrain: TerrainLike, mediaCap: MediaLike, o: { box: [number, number, number, number]; name?: string; viscosity?: number; threshold?: number; depth?: number; every?: number }): Link & { present: boolean } ``` Wet ground is a medium: in a rectangle of the terrain the columns that are wet (moisture at least `threshold`) make a mud medium of the soil's wet density, its top at the mean surface of those columns and its box their extent, so bodies in it feel buoyancy and the viscous drag of D. When the ground dries, or the pit is dug away, the medium goes. It follows the terrain every `every` seconds. ### navFollowsTerrain *function* · `packages/physics-links/src/index.ts:366` ```ts function navFollowsTerrain(world: WorldLike, terrain: { tile: number; x(i: number): number; z(j: number): number }, o: { rebuild: (bounds: { min: [number, number, number]; max: [number, number, number] }) => void; settle?: number; margin?: number }): Link & { dispose(): void; pending: boolean; builds: number } ``` The navigation follows the terrain: the tiles that `terrain:changed` names are joined into one box (with `margin` metres round it), and after `settle` seconds without a further change `rebuild(bounds)` runs, once, so a dug trench is not walked into and a heap is walked over. Digging goes on for many steps; the mesh is built when it stops. ### plasticHeats *function* · `packages/physics-links/src/index.ts:306` ```ts function plasticHeats(link: PlasticLike, part: HeatPartLike, net: HeatNetLike, share = 0.9): Link ``` Plastic work of an E link becomes heat in a part: the force it carried times the plastic length it added, a Taylor-Quinney share (0.9) of it. ### reactorHeatsPart *function* · `packages/physics-links/src/index.ts:208` ```ts function reactorHeatsPart(reactor: ReactorFuel, part: HeatPartLike, net: HeatNetLike, conductance: number): Link ``` The fuel of a reactor conducts heat to a part of H (the vessel, the containment, a pool) through a conductance, W/K. What leaves the fuel enters the part, so after a scram the decay heat that the coolant no longer carries warms the structure instead of vanishing. ### reservoirInPart *function* · `packages/physics-links/src/index.ts:268` ```ts function reservoirInPart(res: ReservoirLike, part: HeatPartLike, net: HeatNetLike, o: { G: number; density: number; cp: number; T0?: number }): Link & { T: number; mass(): number } ``` The liquid of an L1 reservoir takes the part's temperature slowly: heat flows through a conductance G (W/K) into the mass the reservoir holds now (volume x density x cp), so a tank that is filled warms to the wall, a drained one has nothing to warm, and the part is cooled by exactly what the liquid took. `T` is the liquid's temperature; liquid poured in mixes at `inT` by the energy balance. ### screwOnShaft *function* · `packages/physics-links/src/index.ts:119` ```ts function screwOnShaft(thruster: ThrusterLike, shaft: ShaftLike, o: { diameter: number; kt: number; kq: number; rho?: number }): Link ``` A screw on a shaft drives a vessel's thruster: thrust k_T·ρ·n²·D⁴ from the shaft's speed, and the torque k_Q·ρ·n²·D⁵ the water takes back as a load on the shaft (n in revolutions per second). The vessel's speed through the water is not in this law (a bollard pull). ### slipHeats *function* · `packages/physics-links/src/index.ts:70` ```ts function slipHeats(coupling: CouplingLike, part: HeatPartLike, net: HeatNetLike): Link ``` What a coupling loses (a slipping belt or clutch, a brake) heats a part. ### stagnationHeats *function* · `packages/physics-links/src/index.ts:292` ```ts function stagnationHeats(part: HeatPartLike, net: HeatNetLike, o: { speed: () => number; ambient: () => number; G: (v: number) => number; cp?: number; recovery?: number }): Link ``` Stagnation heating (D into H): a body moving at speed v through air at T warms toward its recovery temperature T + r v^2 / (2 cp) (r = 0.85 for a laminar and 0.89 for a turbulent boundary layer), through a heat-transfer conductance G (W/K) that the caller derives from its speed (h A). ### turbineOnReactor *function* · `packages/physics-links/src/index.ts:82` ```ts function turbineOnReactor(reactor: ReactorLike, shaft: ShaftLike, o: { efficiency: number; maxTorque: number }): Link ``` A steam turbine on a reactor's heat sink: of the heat the coolant gives up, `efficiency` becomes shaft work (as a torque on the shaft, power / ω, capped at `maxTorque` at standstill). The rest is the condenser's. ### vesselInPart *function* · `packages/physics-links/src/index.ts:43` ```ts function vesselInPart(vessel: ChemVesselLike, part: HeatPartLike, net: HeatNetLike): Link ``` The chemical vessel sits in a heat part: the part is its surroundings, and what the vessel loses goes into the part. ### wireFire *function* · `packages/physics-links/src/index.ts:251` ```ts function wireFire(world: WorldLike, o: { circuit: string; element: string; target: { ignite(): unknown } | (() => void) }): Link & { dispose(): void; lit: boolean } ``` A wire that overheats past its insulation sets fire to what it lies in (a chamber of K, or any object with `ignite()`), once. ## Interfaces ### BoilerLike *interface* · `packages/physics-links/src/index.ts:36` ```ts interface BoilerLike ``` A boiler (K): steam through an area, taken out with its enthalpy. - `pressure: number` - `flowThrough(area: number, outside?: number): number` - `take(kg: number): number` ### ChemVesselLike *interface* · `packages/physics-links/src/index.ts:26` ```ts interface ChemVesselLike ``` A chemical vessel (Q): its surroundings' temperature and the heat it has lost to them. - `Tenv: number` - `lost: number` - `hA: number` - `entity?: string` ### CouplingLike *interface* · `packages/physics-links/src/index.ts:30` ```ts interface CouplingLike ``` A drivetrain coupling (M) with the energy it has turned into heat (slip, a brake). - `loss: number` ### EnergyTerm *interface* · `packages/physics-links/src/index.ts:167` ```ts interface EnergyTerm ``` One entry in a scene's energy account: a name and how much it holds or has taken, J. - `name: string` - `joules: () => number` ### FeedableBoiler *interface* · `packages/physics-links/src/index.ts:394` ```ts interface FeedableBoiler ``` - `readonly water: number` - `feed(kg: number, T?: number): void` ### GasLike *interface* · `packages/physics-links/src/index.ts:28` ```ts interface GasLike ``` A bounded gas (D): heated at constant volume or pressure. - `temperature: number` - `heat(joules: number, at?: 'volume' | 'pressure'): unknown` ### HeatNetLike *interface* · `packages/physics-links/src/index.ts:24` ```ts interface HeatNetLike ``` What adds heat to a part: `HeatNetwork.add`. - `add(p: HeatPartLike, joules: number): void` ### HeatPartLike *interface* · `packages/physics-links/src/index.ts:22` ```ts interface HeatPartLike ``` A part of the heat network (H). - `T: number` - `fixed: boolean` - `entity?: string` ### KernelLike *interface* · `packages/physics-links/src/index.ts:40` ```ts interface KernelLike ``` A kernel that applies forces. - `applyForce(b: Body, f: Vec3, at?: Vec3): void` ### Link *interface* · `packages/physics-links/src/index.ts:13` ```ts interface Link ``` Links between capabilities: the places where one capability's output is another's input, so a world closes its loops (a fire heats a pot, steam turns a turbine, the turbine a generator, the generator lights a lamp; a screw pushes a ship and loads its engine). Each capability stays ignorant of the others; a link is a small object that reads one side and writes the other once a step, after the capabilities have stepped, and keeps the energy it moves so a scene can account for it. The link reads and writes through the plain fields and methods of the objects it joins (a heat part, a chemical vessel, a gas volume, a shaft, a reactor, a thruster, a kernel body), so this package imports none of their packages. - `readonly kind: string` - `moved: number` — energy moved across the link so far, J (heat into a part, work into a shaft) - `step(dt: number, host: PhysicsHost, contacts: readonly ContactEvent[]): void` ### LinksCapability *interface* · `packages/physics-links/src/index.ts:169` ```ts interface LinksCapability extends Capability ``` - `readonly links: Link[]` - `add(l: L): L` - `readonly terms: EnergyTerm[]` — Terms of the scene's energy account: stores (kinetic, heat, chemical, electric) and sinks (losses, the condenser). - `account(t: EnergyTerm): void` - `energy(): { total: number; terms: Record }` — The sum of every term, J: in a closed scene it stays where it started (`links.energy`). ### MediaLike *interface* · `packages/physics-links/src/index.ts:326` ```ts interface MediaLike ``` - `addMedium(m: { name: string; density: number; viscosity: number; surface?: number; bounds?: { min: Vec3; max: Vec3 } }): void` - `removeMedium(name: string): void` ### PlasticLike *interface* · `packages/physics-links/src/index.ts:304` ```ts interface PlasticLike ``` - `k: number` - `L0: number` - `alpha: number` - `force: number` ### ReactorLike *interface* · `packages/physics-links/src/index.ts:34` ```ts interface ReactorLike ``` A reactor (N): its coolant temperature, flow and the inlet the heat sink returns it at. - `Tc: number` - `flow: number` - `spec: { inlet: number }` ### ReservoirLike *interface* · `packages/physics-links/src/index.ts:262` ```ts interface ReservoirLike ``` - `volume: number` ### ShaftLike *interface* · `packages/physics-links/src/index.ts:32` ```ts interface ShaftLike ``` A drivetrain shaft (M) and the torques acting on it. - `omega: number` - `sources: Array<(omega: number, theta: number, t: number) => number>` ### TerrainLike *interface* · `packages/physics-links/src/index.ts:321` ```ts interface TerrainLike ``` - `readonly nx: number` - `readonly nz: number` - `x(i: number): number` - `z(j: number): number` - `height(i: number, j: number): number` - `moistureAt(i: number, j: number): number` - `topSoil(i: number, j: number): { soil: { density: number; wet?: { density?: number } } }` ### ThrusterLike *interface* · `packages/physics-links/src/index.ts:38` ```ts interface ThrusterLike ``` A thruster of a vessel (V) that takes its thrust from a source. - `source?: (u: number) => number`