# @ferret/physics-media: API

water, mud, wind and air as media with drag, buoyancy and flow; the standard atmosphere.

19 exports. Generated from the source (`packages/physics-media/src`), so it matches the code.

## Classes

### GasVolume

*class* · `packages/physics-media/src/atmosphere.ts:66`

```ts
class GasVolume
```

A bounded amount of gas obeying the ideal gas law p·V = n·R·T: an envelope, an air pocket in a ballast tank, a diving bell.
Not a gas flow field: the whole volume has one pressure and one temperature.

- `moles: number`
- `temperature: number`
- `volume: number`
- `gamma: number` — ratio of specific heats: 1.4 for a diatomic gas such as air
- `molarMass: number` — kg/mol
- `constructor(o: { moles: number; temperature: number; volume: number; gamma?: number; molarMass?: number })`
- `static ofAir(atm: Atmosphere, altitude: number, volume: number): GasVolume` — A volume holding the air of the atmosphere at an altitude (an open envelope at the start).
- `get pressure()`
- `get density()`
- `get mass()`
- `get cv()` — Heat capacity at constant volume, J/K.
- `setVolume(v: number, mode: 'isothermal' | 'adiabatic' = 'isothermal')` — Change the volume; isothermal keeps T (heat flows out), adiabatic keeps the heat in (T changes with V^(1−γ)).
- `heat(joules: number, at: 'volume' | 'pressure' = 'volume')` — Add heat at constant volume (the pressure rises) or at constant pressure (the volume grows). Returns the new volume.
- `addMoles(dn: number)` — Let moles out (a leak) or in.

## Functions

### exponentialAtmosphere

*function* · `packages/physics-media/src/atmosphere.ts:33`

```ts
function exponentialAtmosphere(seaLevelDensity = 1.225, scaleHeight = 8500, temperature = 288.15): Atmosphere
```

Density falls as exp(−h/H) with the scale height H: the simple model for a game world.

### gasMassFlow

*function* · `packages/physics-media/src/atmosphere.ts:55`

```ts
function gasMassFlow(p0: number, T0: number, p1: number, area: number, o: { gamma?: number; R?: number; Cd?: number } = {}): number
```

Mass flow, kg/s, of a perfect gas from a space at `p0`, `T0` through an opening of effective area `area` (m2) into a space at `p1`:
subsonic from the isentropic nozzle law, **choked** when p1/p0 is below the critical ratio (2/(γ+1))^(γ/(γ−1)). `R` is the specific gas constant
J/(kg·K). Zero when p1 >= p0. The one implementation behind combustion chambers, steam ports and the pneumatic network.

### gustAt

*function* · `packages/physics-media/src/index.ts:74`

```ts
function gustAt(t: number, g: GustDef): number
```

A deterministic gust, −1..1 in time: two sines with phases from the seed.

### media

*function* · `packages/physics-media/src/index.ts:89`

```ts
function media(): MediaCapability
```

### sphereCd

*function* · `packages/physics-media/src/index.ts:66`

```ts
function sphereCd(re: number): number
```

Drag coefficient of a sphere against the Reynolds number: Stokes' 24/Re at the bottom, a plateau of about 0.44 at the top.

### submergedFraction

*function* · `packages/physics-media/src/index.ts:58`

```ts
function submergedFraction(y: number, r: number, surface: number): number
```

The fraction of a sphere of radius r with its centre at y that lies below a horizontal plane at `surface` (a spherical cap).

### uniformAtmosphere

*function* · `packages/physics-media/src/atmosphere.ts:43`

```ts
function uniformAtmosphere(density = 1.2, temperature = 288.15): Atmosphere
```

The same air everywhere (a closed hall, a test).

## Interfaces

### AirState

*interface* · `packages/physics-media/src/atmosphere.ts:2`

```ts
interface AirState
```

The air above the ground: density, pressure and temperature by altitude. A game gives its own for another planet or a game world.

- `density: number`
- `pressure: number`
- `temperature: number`

### Atmosphere

*interface* · `packages/physics-media/src/atmosphere.ts:3`

```ts
interface Atmosphere
```

- `at(altitude: number): AirState`

### GustDef

*interface* · `packages/physics-media/src/index.ts:26`

```ts
interface GustDef
```

media. Water, mud, wind, air: a medium has a density and a viscosity (and a flow). A body in it feels
  - drag, Stokes at low Reynolds numbers and quadratic at high ones (Schiller–Naumann for a sphere), against the flow;
  - buoyancy, ρ_medium · V_submerged · g, from the exact submerged part of a sphere (a spherical cap against the surface);
  - rotational drag.
Air is the default medium, with density and temperature from the atmosphere (the International Standard Atmosphere unless the game
gives its own) and a wind that may gust. It can be left off. A body half in water and half in air feels the volume-weighted blend.

values (each at world / level / zone / entity scope):
  air          true: the air is a medium (false = vacuum)                                (true)
  atmosphere   an Atmosphere                                                             (the standard atmosphere)
  seaLevel     the y of altitude zero                                                    (0)
  wind         [x, y, z] m/s at the reference height; windExponent / windRefHeight give a power-law profile (0 = uniform)
  gust         { amplitude, period, seed? }: a deterministic gust along the wind
  media        MediumDef[]: { name, density, viscosity, flow?, surface?, zone? } — `surface` is the y of the top of the water,
               `zone` limits the medium to a zone of

- `amplitude: number`
- `period: number`
- `seed?: number`

### MediaCapability

*interface* · `packages/physics-media/src/index.ts:79`

```ts
interface MediaCapability extends Capability
```

- `media: Map<string, MediumDef>`
- `addMedium(m: MediumDef): void`
- `removeMedium(name: string): void`
- `at(host: PhysicsHost, p: Vec3, ctx?: ScopeContext): MediumSample` — The medium at a point.
- `sample(host: PhysicsHost, p: Vec3, r: number, ctx?: ScopeContext): { density: number; viscosity: number; flow: Vec3; fraction: number; medium: string }` — The blend a sphere of radius r at p sits in.

### MediumDef

*interface* · `packages/physics-media/src/index.ts:27`

```ts
interface MediumDef
```

- `name: string`
- `density: number`
- `viscosity: number`
- `flow?: Vec3`
- `surface?: number | (() => number)` — the y of the top of the medium; a function when it moves (a reservoir that fills and drains)
- `zone?: string`
- `bounds?: { min: Vec3; max: Vec3 }` — the box the medium fills (a tank): outside it the medium is not there
- `gust?: GustDef`

## Constants

### EXAMPLE_MEDIA

*const* · `packages/physics-media/src/index.ts:50`

```ts
const EXAMPLE_MEDIA: { readonly water: { readonly name: "water"; readonly density: 998; readonly viscosity: 0.001; }; readonly seawater: { readonly name: "seawater"; readonly density: 1025; readonly viscosity: 0.0011; }; readonly mud: { readonly name: "mud"; readonly density: 1800; readonly viscosity: 0.5; }; readonly honey: { readonly name: "honey"; readonly density: 1420; readonly viscosity: 10; }; }
```

Water, mud and honey, as examples.

### MEDIA_DEFAULTS

*const* · `packages/physics-media/src/index.ts:44`

```ts
const MEDIA_DEFAULTS: { air: boolean; atmosphere: Atmosphere; seaLevel: number; wind: Vec3; windExponent: number; windRefHeight: number; gust: GustDef | undefined; media: MediumDef[]; cd: number | undefined; angularDrag: boolean; samples: number; }
```

### R_AIR

*const* · `packages/physics-media/src/atmosphere.ts:5`

```ts
const R_AIR: 287.052874
```

### R_GAS

*const* · `packages/physics-media/src/atmosphere.ts:6`

```ts
const R_GAS: 8.314462618
```

### standardAtmosphere

*const* · `packages/physics-media/src/atmosphere.ts:10`

```ts
const standardAtmosphere: Atmosphere
```

The International Standard Atmosphere up to 47 km (troposphere, tropopause, stratosphere layers), clamped below sea level to sea-level values.

### vacuum

*const* · `packages/physics-media/src/atmosphere.ts:48`

```ts
const vacuum: Atmosphere
```

No air: a vacuum (space, a vacuum chamber).