buoyancy

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.

Plain text

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	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.

buoyancy

Fields

Rules that can refuse it