# buoyancy

> Talos next · Since 0.6; changed in 0.7

Makes a dynamic body float on the scene's sea (`meta.environment.ocean`): every tick, before the physics step, the engine reads the sea at each of the body's probes and adds a buoyancy force (the weight of the water the probe displaces) and a drag force.

Whether the body floats is its mass against the water it displaces; the component holds no density. The entity needs a `rigidbody` of kind `dynamic` (`buoyancy-without-body`) and the scene needs a fluid: an ocean, a `water` or `waterways` component, or `meta.environment.air` (`buoyancy-without-ocean`). With `meta.environment.air`, the body's probes out of the water are buoyed by the air and dragged against the wind, with the drags scaled by the air's density over the water's. It works in standard projects and on headless runs.

Use it in a scene entity's `components` list as `{ "type": "buoyancy", … }`. The contract writes the fields flat and refuses unknown keys.

## Fields

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| `probes` | `BuoyancyProbe[]` | no |  |  | The hull as probes, 1..256. Absent: the engine cuts the collider's local bounds into a `resolution` x `resolution` x `resolution` grid of cells (a convex or mesh collider uses its bounds, scaled by `volumeScale`). Author probes by hand for a hull whose bounds are not its shape. |
| `resolution` | `number` | no | `3` |  | Absent `probes` only: cells per axis, a whole number 1..8. Default 3. At most 256 cells are used (`physics.buoyancy.probe-cap` when a grid was clamped). |
| `volumeScale` | `number` | no | `1` |  | The fraction of the collider's volume that displaces water, 0.05..1. Default 1. Below 1 is a hollow hull that floats higher. |
| `linearDrag` | `number` | no | `500` |  | Drag proportional to speed through the water, N s/m per submerged cubic metre, 0 or more. Default 500. |
| `quadraticDrag` | `number` | no | `500` |  | Drag proportional to speed squared, N s2/m2 per submerged cubic metre, 0 or more. Default 500. |
| `waterVelocity` | `boolean` | no | `true` |  | Drag is measured against the wave's orbital velocity, not still water. Default true. |
| `angularDrag` | `number` | no |  |  | Damping of the body's spin, N m s per submerged cubic metre, 0 or more: a torque against the angular velocity. Default 0 (none). In air it is scaled by the air's density over the water's, as the drags are. |

## Rules that can refuse it

- `buoyancy-without-body`
- `buoyancy-without-ocean`
- `ocean-weather-not-ascending`
- `physics.buoyancy.force-refused`
- `physics.buoyancy.probe-cap`
- `render-ocean-without-hd`
- `render-waterways-without-hd`
- `watercraft-without-buoyancy`