# @ferret/physics-impact: API

elastic and inelastic collisions, rest thresholds, sticking, impact events.

elastic and inelastic collisions. The kernel already bounces by the restitution of the two materials; this adds what a
game dials per scope: the speed below which a bounce is a rest, a restitution scale, a loss of bounce at high impact speed,
a perfectly inelastic mode (the bodies stick and move as one), and an event with the impulse and the energy lost.

values (each at world / level / zone / entity scope):
  threshold      closing speed (m/s) below which a bounce is a rest              (kernel default 0.2)
  scale          multiplies the restitution (0 = every hit is inelastic)         (1)
  falloff        { from, to, factor }: restitution falls linearly from 1x at `from` m/s to `factor` x at `to` m/s
  stick          true: two dynamic bodies that hit leave as one body              (false)
  minEventSpeed  smallest closing speed that raises `physics:impact`              (0.1)

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

## Functions

### impact

*function* · `packages/physics-impact/src/index.ts:34`

```ts
function impact(): Capability
```

## Interfaces

### ImpactEvent

*interface* · `packages/physics-impact/src/index.ts:16`

```ts
interface ImpactEvent
```

- `a: Body`
- `b: Body`
- `entityA?: unknown`
- `entityB?: unknown`
- `point: Vec3`
- `normal: Vec3`
- `impulse: number` — normal impulse over the step, N·s
- `speed: number` — closing speed, m/s
- `restitution: number` — the restitution the hit was solved with (0 when below the threshold)
- `energyLost: number` — kinetic energy turned into heat and deformation, J: ½·μ·(1 − e²)·v² with the reduced mass μ
- `stuck: boolean`

### ImpactFalloff

*interface* · `packages/physics-impact/src/index.ts:15`

```ts
interface ImpactFalloff
```

elastic and inelastic collisions. The kernel already bounces by the restitution of the two materials; this adds what a
game dials per scope: the speed below which a bounce is a rest, a restitution scale, a loss of bounce at high impact speed,
a perfectly inelastic mode (the bodies stick and move as one), and an event with the impulse and the energy lost.

values (each at world / level / zone / entity scope):
  threshold      closing speed (m/s) below which a bounce is a rest              (kernel default 0.2)
  scale          multiplies the restitution (0 = every hit is inelastic)         (1)
  falloff        { from, to, factor }: restitution falls linearly from 1x at `from` m/s to `factor` x at `to` m/s
  stick          true: two dynamic bodies that hit leave as one body              (false)
  minEventSpeed  smallest closing speed that raises `physics:impact`              (0.1)

- `from: number`
- `to: number`
- `factor: number`

## Constants

### IMPACT_DEFAULTS

*const* · `packages/physics-impact/src/index.ts:30`

```ts
const IMPACT_DEFAULTS: { threshold: number | undefined; scale: number; falloff: ImpactFalloff | undefined; stick: boolean; minEventSpeed: number; }
```