# @ferret/physics-gravity: API

gravity as a field with uniform vectors per scope and point attractors.

gravity as a field. A uniform vector (override per zone, level or entity), point attractors (a planet, a pit,
inverse square with a softening radius so nothing divides by zero), and a scale per body or entity. With G on, the kernel's
own constant gravity is switched off and this field supplies every force, so one law serves the cannonball, the character
(which reads `host.fields.gravity`) and anything a game adds.

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

## Functions

### gravity

*function* · `packages/physics-gravity/src/index.ts:41`

```ts
function gravity(): GravityCapability
```

## Interfaces

### Attractor

*interface* · `packages/physics-gravity/src/index.ts:10`

```ts
interface Attractor
```

gravity as a field. A uniform vector (override per zone, level or entity), point attractors (a planet, a pit,
inverse square with a softening radius so nothing divides by zero), and a scale per body or entity. With G on, the kernel's
own constant gravity is switched off and this field supplies every force, so one law serves the cannonball, the character
(which reads `host.fields.gravity`) and anything a game adds.

- `id: string`
- `position?: Vec3` — a fixed point, or an entity whose node is the centre
- `entity?: string`
- `mu?: number` — gravitational parameter G·M (m³/s²); or give the surface gravity and the radius of the body
- `surfaceGravity?: number`
- `radius?: number`
- `softening?: number` — below this distance the pull stops growing (default 0.1 × radius, or 0.5 m)
- `range?: number` — beyond this distance the attractor does nothing (default: unlimited)

### GravityCapability

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

```ts
interface GravityCapability extends Capability
```

- `attractors: Map<string, Attractor>`
- `addAttractor(a: Attractor): void`
- `removeAttractor(id: string): void`
- `at(host: PhysicsHost, p: Vec3, ctx?: ScopeContext): Vec3` — Gravity acceleration at a point (m/s²): the field vector of its scope plus every attractor, times the scale.

## Constants

### GRAVITY_DEFAULTS

*const* · `packages/physics-gravity/src/index.ts:25`

```ts
const GRAVITY_DEFAULTS: { vector: Vec3; scale: number; }
```