Talos Engine
Get started
Menu
Talos docs

buoyancy

Since 0.6Changed 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.

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

FieldTypeRequiredDefaultAllowed valuesDescription
probesBuoyancyProbe[]noThe 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.
resolutionnumberno3Absent 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).
volumeScalenumberno1The fraction of the collider's volume that displaces water, 0.05..1. Default 1. Below 1 is a hollow hull that floats higher.
linearDragnumberno500Drag proportional to speed through the water, N s/m per submerged cubic metre, 0 or more. Default 500.
quadraticDragnumberno500Drag proportional to speed squared, N s2/m2 per submerged cubic metre, 0 or more. Default 500.
waterVelocitybooleannotrueDrag is measured against the wave's orbital velocity, not still water. Default true.
angularDragnumbernoDamping 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