---
name: ferret-physics-gravity-media
description: Use for gravity and fluids acting on bodies in Ferret: uniform and zone gravity, planets and attractors, per-body scale, weightlessness; and media with drag and buoyancy (water, mud, wind, air by altitude), gas volumes, currents, gusts, wading.
---

# Gravity and media

## When to use
A low-gravity room, a planetoid, floating and sinking, drag in mud, wind that gusts, vacuum.

## The model
Gravity is a **field**: a uniform vector per scope, point attractors (inverse square with softening), a scale per body. With it on, the kernel's own gravity is switched off and the character reads the field. Media (water, mud, honey, wind, air) give drag (linear then quadratic) and buoyancy against the true volume below the surface; the standard atmosphere varies by altitude; `GasVolume` is a closed gas.

## Steps
1. Register and enable `gravity` / `media` (`ferret-physics-host`).
2. Gravity: set the vector at world, zone or entity scope; attractors need `mu`, or `surfaceGravity` and `radius`.
3. A medium needs a place (`surface`, `zone` or `bounds`); wind is air's and is set in the zone scope.
4. A body floats when its density (mass / volume) is below the medium's.
5. Commands: `gravity.at|set|scale`, `gravity.attractor.add`, `media.add|at`, `wind.set`, `atmosphere.at`.

## Check afterwards
A dropped sphere falls at the expected rate; `media.at` at the body's position names the medium; a floating body settles at `m / (ρ A)` draft.

## What usually goes wrong
- A body does not fall: scale 0, `gravityScale` 0, static, or exempt.
- Gravity doubled: kernel gravity on **and** your own force.
- A zone has no effect: no `ZoneService`, or the body's *position* (not extent) is outside.
- A medium with no place fills the whole world.
- Bodies shoot off near an attractor: softening too small.

## Files

- `reference/gravity.md` — Gravity as a field: a uniform vector per scope, point attractors and planets, per-body scale, weightlessness, and how characters and other capabilities read it.
- `reference/media.md` — Drag and buoyancy in water, mud, honey, wind and air; the atmosphere by altitude; gas volumes; floating, sinking, currents, gusts and wading.
- `reference/api-physics-gravity.md` — every export of `@ferret/physics-gravity` with signature and doc comment
- `reference/api-physics-media.md` — every export of `@ferret/physics-media` with signature and doc comment
- `reference/commands.md` — 10 commands of these packages with their arguments