# buoyancy

> Talos 0.6 · Since 0.6

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 water: an ocean or a `water` component (`buoyancy-without-ocean`). 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. |

## 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`