Buoyancy

Floats the entity's rigid body on any water: a sea, a Terrain's lakes and rivers, a Water component's pool, a body Physics.defineWater declares.

entity.find("barrel").component.add("Buoyancy", { density = 0.4 })

The entity needs a dynamic Physics body. Position and orientation stay the physics world's: this component adds the forces water exerts, inside every physics step, so a floating body still collides, still takes impulses, still falls when it is lifted clear of the water, and floats the same way at any frame rate.

Field	What it does
density	Relative to water: that share of the hull rides under still water, so the lower it is the higher the hull floats, and a body denser than water sinks. It holds whatever mass the body was given. 0 releases the body.
damping	How quickly water settles the hull's bobbing and rolling: the factor on the waves its motion makes at the surface. 1 settles it within a few swings, 0 leaves it bobbing.
hull	What the hull is measured from: "colliders" (the default), the body's own solid colliders, or "model", the box around what the entity draws.
sizeX/sizeY/sizeZ	A box that displaces water in place of the colliders or the model, centred on the entity's origin. All three at 0 measures the hull as hull says.

The colliders are what the hull is by default (a box, a ball, a capsule, a convex hull, a closed mesh, or several on the body and its children), so an invisible collision proxy under detailed art floats by the proxy. A body with nothing to measure (no dynamic Physics body, only sensor colliders, a model hull that draws nothing) is refused a second after it is attached, with a warning that names the entity and what to add, and floats as soon as it has it.

barrel:submersion() reads how much of the hull was under water on the last physics step, and barrel:waterline() reads the world Y the surface stood at under it, wave motion included.

Forces reach a rigid body only while the scene is playing, so a hull sits where it was placed in edit mode and settles onto the water when play starts.