Documentation / scene / BuoyancyVolume
Class: BuoyancyVolume
Defined in: libs/scene/src/utility/buoyancy.ts:90
The buoyancy a box-shaped hull gets from a water surface, as a force and a torque, independent of what integrates them.
Pair it with FloatingBody for a self-contained float, or feed the force and torque to a rigid body in whatever physics library the application uses.
The model
The hull is filled with a lattice of probes, each a block of hull carrying an equal share of the lift the whole hull can produce, scaled by how much of the block is under water. Summed, that is the buoyancy of whatever part of the hull is submerged, acting at that part's centroid - which is the centre of buoyancy, and the thing a righting moment is made of: the water pushes up hardest on whichever side has more of its blocks under, which rolls a boat back upright. There is no separate upright target.
The lattice fills the box rather than sitting on the bottom face. Probes on the bottom alone are exact for a level hull and wrong the moment it rolls: the columns rise vertically through where the side wall used to be, and the net moment pushes the roll further over instead of back.
The lift a fully submerged hull produces is mass * g / submergedFraction: the force that, once the configured share of the probes is under, balances the weight. That makes submergedFraction the density ratio and the only thing that sets the float height, and it makes the mass drop out of the buoyant motion altogether - lift and inertia both scale with it. Tying lift to mass rather than to geometry also means a heavy body cannot sink past its deck, where the waterplane and the righting moment would vanish.
What is not modelled
No hull-volume integral, no added mass, no drag. A probe's contribution grows linearly with depth up to its own height, which is accurate while a vessel rides on its waterline and approximate for a fully submerged one.
Constructors
Constructor
new BuoyancyVolume(
options):BuoyancyVolume
Defined in: libs/scene/src/utility/buoyancy.ts:115
Creates a buoyancy volume.
Parameters
options
Returns
BuoyancyVolume
Properties
size
readonlysize:Vector3
Defined in: libs/scene/src/utility/buoyancy.ts:92
Full extents in metres, in local axes.
mass
readonlymass:number
Defined in: libs/scene/src/utility/buoyancy.ts:94
Mass in kilograms.
submergedFraction
readonlysubmergedFraction:number
Defined in: libs/scene/src/utility/buoyancy.ts:96
Share of the height under water at rest.
gravity
readonlygravity:number
Defined in: libs/scene/src/utility/buoyancy.ts:98
Gravity in metres per second squared.
maxBuoyancy
readonlymaxBuoyancy:number
Defined in: libs/scene/src/utility/buoyancy.ts:100
Lift of the fully submerged hull, in newtons.
draft
readonlydraft:number
Defined in: libs/scene/src/utility/buoyancy.ts:102
Height of the waterline above the bottom face at rest, in metres.
restHeight
readonlyrestHeight:number
Defined in: libs/scene/src/utility/buoyancy.ts:104
Height of the hull's centre above the still-water level at rest, in metres.
probes
readonlyprobes:Vector3[]
Defined in: libs/scene/src/utility/buoyancy.ts:106
Probe centres in local space.
probeHeight
readonlyprobeHeight:number
Defined in: libs/scene/src/utility/buoyancy.ts:108
Height of one probe's block, in metres.
Methods
restY()
restY(
waterLevel):number
Defined in: libs/scene/src/utility/buoyancy.ts:148
World Y the hull's centre rests at on a still surface at waterLevel.
Parameters
waterLevel
number
Returns
number
computeForces()
computeForces(
position,rotation,waveHeight,waterLevel,outForce,outTorque):number
Defined in: libs/scene/src/utility/buoyancy.ts:164
Buoyant force and torque on the hull at a pose, in world space, about the hull's centre. Gravity is not included.
Parameters
position
Vector3
World position of the hull's centre.
rotation
Quaternion
World orientation of the hull.
waveHeight
Surface height above waterLevel at a world XZ.
waterLevel
number
World Y of the still-water level.
outForce
Vector3
Receives the force in newtons.
outTorque
Vector3
Receives the torque in newton-metres.
Returns
number
How much of the hull is under water, 0 to 1. Useful for blending drag between air and water.