# @ferret/physics-strength: API

finite strength: bodies that take damage and break into pieces, links that break.

finite strength. Bodies take damage from hard hits and break; links between bodies break when the force on them
passes what the material holds.

values (each at world / level / zone / entity scope):
  toughness   impulse (N·s) a body can absorb before it breaks; Infinity = unbreakable                  (Infinity)
  threshold   impulse of one hit below which nothing is taken                                           (0)
  scale       multiplies the damage taken                                                               (1)
  pieces      how many fragments replace a body that breaks; 0 = only the event, the body stays         (0)
  burst       speed (m/s) the fragments fly apart at, on top of the parent's velocity                   (1)

events: `physics:damage` { entity, body, amount, health }, `physics:break` { entity, body, point, impulse, pieces },
        `physics:joint-break` { constraint, force, userData }.

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

## Functions

### strength

*function* · `packages/physics-strength/src/index.ts:65`

```ts
function strength(): StrengthCapability
```

## Interfaces

### BreakEvent

*interface* · `packages/physics-strength/src/index.ts:38`

```ts
interface BreakEvent
```

`seed`: the same seed on another machine (`breakNow(target, point, seed)`) gives the same pieces and the same scatter.

- `entity?: Entity`
- `body: Body`
- `point: Vec3`
- `impulse: number`
- `pieces: Entity[]`
- `seed: number`

### DamageEvent

*interface* · `packages/physics-strength/src/index.ts:36`

```ts
interface DamageEvent
```

- `entity?: Entity`
- `body: Body`
- `amount: number`
- `health: number`

### JointDef

*interface* · `packages/physics-strength/src/index.ts:21`

```ts
interface JointDef
```

- `type: ConstraintType`
- `a: Entity | Body`
- `b: Entity | Body`
- `length?: number`
- `stiffness?: number`
- `damping?: number`
- `tensile?: number` — tensile strength of the material, Pa; with `area` it gives the force the joint holds: σ·A
- `area?: number` — cross-section, m²
- `maxForce?: number` — the force held, N, when it is not given as strength and area
- `userData?: unknown`

### StrengthCapability

*interface* · `packages/physics-strength/src/index.ts:40`

```ts
interface StrengthCapability extends Capability
```

- `joint(def: JointDef): Constraint` — Join two bodies with a link that breaks.
- `damage(target: Entity | Body, amount: number, point?: Vec3): number` — Take damage off a body (an explosion, a command); breaks it at zero.
- `breakNow(target: Entity | Body, point?: Vec3, seed?: number): void` — Break a body now, whatever its toughness (a blast that passed its rupture limit).
- `health(target: Entity | Body): number` — What a body has left (its toughness when untouched; Infinity when unbreakable).

## Constants

### STRENGTH_DEFAULTS

*const* · `packages/physics-strength/src/index.ts:19`

```ts
const STRENGTH_DEFAULTS: { toughness: number; threshold: number; scale: number; pieces: number; burst: number; maxPieces: number; }
```

`maxPieces`: pieces alive at once over the whole world; past it a body still breaks (the event) but leaves no new pieces.