# @ferret/physics-explosions: API

blast waves, craters, fragments and spall from scaled-distance laws.

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

## Functions

### arrivalTime

*function* · `packages/physics-explosions/src/blast.ts:47`

```ts
function arrivalTime(r: number, tnt: number, curve: BlastCurve = KINNEY_GRAHAM): number
```

Time the front takes to reach r: the integral of dR / U with the Rankine-Hugoniot shock speed U = c·sqrt(1 + 6 Ps / 7 P0).

### blastAt

*function* · `packages/physics-explosions/src/blast.ts:40`

```ts
function blastAt(r: number, tnt: number, curve: BlastCurve = KINNEY_GRAHAM): BlastPoint
```

The blast at distance r from a charge of `tnt` kg: the wave is taken as a triangle, so the impulse is Ps·t+/2.

### blastLoad

*function* · `packages/physics-explosions/src/blast.ts:154`

```ts
function blastLoad(ps: number, area: number, drag = 1, ambient = P_ATM): number
```

Force a drag body takes in the blast: (peak overpressure around it, in the diffraction phase) plus drag times dynamic pressure.

### blastWind

*function* · `packages/physics-explosions/src/blast.ts:148`

```ts
function blastWind(ps: number, ambient = P_ATM): { speed: number; dynamic: number }
```

Wind behind the front: speed u = c 5 Ps / (7 P0) / sqrt(1 + 6 Ps / 7 P0) and the dynamic pressure q = 5 Ps^2 / (2 (7 P0 + Ps)) that pushes on what stands in it.

### craterRadius

*function* · `packages/physics-explosions/src/blast.ts:127`

```ts
function craterRadius(law: CraterLaw, tnt: number, burial = 0): number
```

Crater radius for a charge of `tnt` kg whose centre is buried `burial` m: the surface-burst scaling times a burial factor.

### diffracted

*function* · `packages/physics-explosions/src/blast.ts:180`

```ts
function diffracted(tnt: number, source: number[], edge: number[], target: number[], curve: BlastCurve = KINNEY_GRAHAM): { path: number; turn: number; overpressure: number; arrival: number }
```

Diffraction around an edge, as a path and a loss: the front reaches a point in the shadow by the way over the edge (path = to the edge +
from the edge), so it arrives later and lower than in the open: the pressure is the free-field value at that path length times
`1 / (1 + turn / pi x 2)`, where `turn` is the angle the way bends at the edge (0 = no shadow). It is an engineering approximation, not a
wave solution: it is continuous at the shadow boundary, falls with the bend and with the longer path.

### ejecta

*function* · `packages/physics-explosions/src/blast.ts:196`

```ts
function ejecta(craterR: number, mass: number, gravity = 9.81, mu = 0.55, c = 0.5): Ejecta
```

What a crater throws out (Housen-Holsapple scaling): material leaving at radius r from the centre goes at v = c sqrt(g R) (R / r)^(1/mu),
so the mass faster than v is the whole ejected mass x (v / v(R))^(-3 mu) and it lands at v^2 sin(2 angle) / g.

### explosions

*function* · `packages/physics-explosions/src/index.ts:107`

```ts
function explosions(o: ExplosionOptions = {}): ExplosionCapability
```

### gurneyVelocity

*function* · `packages/physics-explosions/src/blast.ts:82`

```ts
function gurneyVelocity(casing: number, charge: number, shape: CasingShape = 'cylinder', gurney = TNT_GURNEY): number
```

Gurney: v = sqrt(2E) / sqrt(M/C + k), with k = 1/2 (cylinder), 3/5 (sphere), 1/3 (open plate, one side).

### mottMasses

*function* · `packages/physics-explosions/src/blast.ts:97`

```ts
function mottMasses(total: number, mu: number, rand: () => number, max = 10000): number[]
```

Mott: masses of fragments with the cumulative number N(m) = (M / 2mu)·exp(-sqrt(m/mu)); so the mean mass is 2·mu and the number M/(2·mu).
The masses are drawn as mu·E² with E exponential, then scaled so they add up to M exactly.

### obliqueReflection

*function* · `packages/physics-explosions/src/blast.ts:142`

```ts
function obliqueReflection(ps: number, incidence: number, ambient = P_ATM): number
```

The reflected overpressure at an incidence angle (0 = head on, 90 deg = grazing): the head-on value blends to the incident one with cos^2, a standard engineering fit that Mach reflection beyond about 40 deg only raises.

### penetrate

*function* · `packages/physics-explosions/src/index.ts:40`

```ts
function penetrate(o: { mass: number; speed: number; angle: number; area: number } & Armour & { grazing?: number }): Penetration
```

What a fragment does to a plate, by its energy against the work of pushing a hole through: the plate resists with its strength over
the fragment's presented area along the slant thickness t / cos θ (θ from the plate's normal). Through when the energy is more than
that work, with the speed the rest gives; stopped in it otherwise, at the depth the energy reaches; and at a grazing angle (past
`grazing`, 70° by default) a fragment that could not get through the slant skids off: a ricochet.

### radiusFor

*function* · `packages/physics-explosions/src/blast.ts:59`

```ts
function radiusFor(pressure: number, tnt: number, curve: BlastCurve = KINNEY_GRAHAM): number
```

The distance at which the peak overpressure falls to `pressure` (Pa); the radius of a given damage ring.

### reflectedPressure

*function* · `packages/physics-explosions/src/blast.ts:137`

```ts
function reflectedPressure(ps: number, ambient = P_ATM): number
```

Peak pressure on a wall the front meets head on (normal reflection of an ideal gas): Pr = 2Ps (7P0 + 4Ps) / (7P0 + Ps), so 2 Ps for a weak wave and up to 8 Ps for a strong one.

### rng

*function* · `packages/physics-explosions/src/blast.ts:88`

```ts
function rng(seed: number)
```

A seeded generator (mulberry32): the same seed, the same pieces.

### scaledDistance

*function* · `packages/physics-explosions/src/blast.ts:35`

```ts
function scaledDistance: (r: number, tnt: number) => number
```

Hopkinson-Cranz scaled distance, m/kg^(1/3).

### spall

*function* · `packages/physics-explosions/src/blast.ts:164`

```ts
function spall(stress: number, duration: number, tensile: number, density: number, waveSpeed: number, wall: number): Spall
```

Hopkinson spalling: the compression pulse in a wall (peak `stress`, length `duration` x wave speed) comes back from the free back face as
tension; it tears off a slab where the tension passes `tensile`, a slab as thick as the length of the pulse's part that exceeds it
(at most half the wall), and the slab leaves with the momentum of the pulse above the strength: speed = impulse above it / (rho x slab).

### underwaterAt

*function* · `packages/physics-explosions/src/blast.ts:67`

```ts
function underwaterAt(r: number, tnt: number): { overpressure: number; theta: number; impulse: number }
```

Under water (Cole): the peak pressure and the decay constant of the exponential pulse; the impulse is their product.

### vesselTnt

*function* · `packages/physics-explosions/src/blast.ts:74`

```ts
function vesselTnt(pressure: number, volume: number, gamma = 1.4, ambient = P_ATM): number
```

The charge of a vessel bursting under pressure (Brode): E = (p1 - p0)·V / (gamma - 1), as kg of TNT.

## Interfaces

### Armour

*interface* · `packages/physics-explosions/src/index.ts:31`

```ts
interface Armour
```

A plate a fragment meets: its thickness (m) and the stress (Pa) it resists a projectile with (≈ 3× the tensile strength for steel).

- `thickness: number`
- `strength: number`

### BlastCurve

*interface* · `packages/physics-explosions/src/blast.ts:14`

```ts
interface BlastCurve
```

- `overpressure(z: number): number` — peak incident overpressure, Pa, at scaled distance z (m/kg^(1/3))
- `duration(z: number): number` — positive-phase duration, s per kg^(1/3)

### BlastPoint

*interface* · `packages/physics-explosions/src/blast.ts:37`

```ts
interface BlastPoint
```

- `overpressure: number`
- `duration: number`
- `impulse: number`
- `arrival: number`
- `scaled: number`

### Casing

*interface* · `packages/physics-explosions/src/index.ts:49`

```ts
interface Casing
```

- `mass: number`
- `shape?: CasingShape`
- `mu?: number`
- `density?: number`
- `gurney?: number`

### CraterLaw

*interface* · `packages/physics-explosions/src/blast.ts:106`

```ts
interface CraterLaw
```

- `k: number` — apparent radius of a surface burst of 1 kg: R = k·W^(1/3.4), m
- `depthRatio: number` — depth / radius of the apparent crater
- `camouflet: number` — scaled depth of burial (m/kg^(1/3)) at which no crater opens (a camouflet)
- `throw: number` — share of the heap thrown out beyond the rim

### DetonateDef

*interface* · `packages/physics-explosions/src/index.ts:50`

```ts
interface DetonateDef
```

- `at: Vec3`
- `tnt?: number` — kg of TNT equivalent, or ...
- `energy?: number` — ... joules
- `burst?: BurstKind`
- `burial?: number` — depth of the charge centre under the ground, m
- `casing?: Casing`
- `seed?: number`
- `vessel?: { pressure: number; volume: number; gamma?: number }` — a vessel that bursts: {pressure, volume, gamma?} (Brode) in place of tnt

### Ejecta

*interface* · `packages/physics-explosions/src/blast.ts:191`

```ts
interface Ejecta
```

- `velocity: (r: number) => number`
- `massFaster: (v: number) => number`
- `range: (r: number, angle?: number) => number`
- `total: number`

### ExplosionCapability

*interface* · `packages/physics-explosions/src/index.ts:87`

```ts
interface ExplosionCapability extends Capability
```

- `detonate(def: DetonateDef): ExplosionResult`
- `preview(tnt: number, pressures: number[]): number[]` — Radii (m) at which the peak overpressure falls to each of the given values (Pa).
- `setTerrain(t: Terrain | undefined): void`
- `readonly fragments: ReadonlySet<Entity>`

### ExplosionOptions

*interface* · `packages/physics-explosions/src/index.ts:75`

```ts
interface ExplosionOptions
```

- `terrain?: Terrain`
- `curve?: BlastCurve`
- `craters?: Record<string, CraterLaw>`
- `maxFragments?: number` — fragments alive at once; the oldest are recycled
- `perFrame?: number` — fragments created per step
- `fragmentLife?: number` — seconds a fragment lives

### ExplosionResult

*interface* · `packages/physics-explosions/src/index.ts:65`

```ts
interface ExplosionResult
```

- `tnt: number`
- `effective: number` — effective yield after the ground reflection / coupling, kg
- `bodies: number`
- `fragments: number`
- `crater?: { radius: number; depth: number; removed: number; thrown: number; fallback: number }`
- `camouflet: boolean`

### Penetration

*interface* · `packages/physics-explosions/src/index.ts:32`

```ts
interface Penetration
```

- `outcome: 'through' | 'stopped' | 'ricochet'`
- `depth: number`
- `exitSpeed: number`
- `slant: number`

### Spall

*interface* · `packages/physics-explosions/src/blast.ts:158`

```ts
interface Spall
```

- `spalls: boolean`
- `thickness: number`
- `speed: number`

### WallSpec

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

```ts
interface WallSpec
```

A wall that a blast meets: its tensile strength (Pa), density, speed of sound in it and thickness (m); when the reflected pulse tears a slab off the back, `explosion:spall` follows.

- `tensile: number`
- `density: number`
- `waveSpeed: number`
- `thickness: number`

## Types

### BurstKind

*type* · `packages/physics-explosions/src/index.ts:47`

```ts
type BurstKind = 'air' | 'surface' | 'buried' | 'water'
```

### CasingShape

*type* · `packages/physics-explosions/src/blast.ts:79`

```ts
type CasingShape = 'cylinder' | 'sphere' | 'plate'
```

## Constants

### EXAMPLE_CRATERS

*const* · `packages/physics-explosions/src/blast.ts:117`

```ts
const EXAMPLE_CRATERS: Record<string, CraterLaw>
```

### EXPLOSION_DEFAULTS

*const* · `packages/physics-explosions/src/index.ts:28`

```ts
const EXPLOSION_DEFAULTS: { minPressure: number; rupture: number; area: number | undefined; transmission: number; spread: number; armour: Armour | undefined; wall: WallSpec | undefined; }
```

### KINNEY_GRAHAM

*const* · `packages/physics-explosions/src/blast.ts:21`

```ts
const KINNEY_GRAHAM: BlastCurve
```

### P_ATM

*const* · `packages/physics-explosions/src/blast.ts:9`

```ts
const P_ATM: 101325
```

### SOUND_SPEED

*const* · `packages/physics-explosions/src/blast.ts:10`

```ts
const SOUND_SPEED: 340.3
```

### TNT_GURNEY

*const* · `packages/physics-explosions/src/blast.ts:12`

```ts
const TNT_GURNEY: 2440
```

Gurney constant sqrt(2E) of TNT, m/s

### TNT_JOULES_PER_KG

*const* · `packages/physics-explosions/src/blast.ts:8`

```ts
const TNT_JOULES_PER_KG: 4184000
```

The laws of a blast as plain functions: scaled distance, overpressure, positive-phase duration and impulse, the under-water pulse,
Gurney velocity, Mott fragment masses and cratering. Units are SI; yield is in kilograms of TNT equivalent.

The air curve is the Kinney-Graham fit of the free-air burst; it is the data slot a Kingery-Bulmash table can replace
(`BlastCurve`), and every capability function below takes the curve as an argument.