Documentation / scene / WaterInteraction
Class: WaterInteraction
Defined in: libs/scene/src/render/water_interaction.ts:588
A local, dynamic height field layered on top of a water surface, driven by things that touch it.
The wave generator gives the surface its ambient motion and knows nothing about what is in the water. This adds what it cannot: a ring spreading from a dropped stone, the wake behind a hull, the slap of a foot. It is a 2D wave equation integrated on a square window of texels aligned to the world, and the water material adds its height and slope to whatever the generator produced, so the ambient sea and the disturbances compose.
The window follows a focus point - the camera by default - and covers windowSize metres at resolution texels. Its origin is snapped to the texel grid, so moving it is an integer shift of the field rather than a resample, and nothing smears. What scrolls in is still water.
The scheme is explicit and needs waveSpeed * dt / texel to stay under the CFL bound; the setters clamp waveSpeed to what the current window allows, so the field cannot be driven unstable from the outside. A sponge band inside the window's edge absorbs outgoing waves so they do not reflect back off the window boundary, which is a boundary of the simulation and not of the water.
Attach it with Water.interaction. Steps run in Water.update on the water's own clock, so pausing the water pauses this too.
Extends
Disposable
Constructors
Constructor
new WaterInteraction():
WaterInteraction
Defined in: libs/scene/src/render/water_interaction.ts:634
Creates a water interaction field.
Returns
WaterInteraction
Overrides
Disposable.constructor
Accessors
disposed
Get Signature
get disposed():
boolean
Defined in: libs/base/dist/index.d.ts:6107
Returns
boolean
Inherited from
Disposable.disposed
resolution
Get Signature
get resolution():
number
Defined in: libs/scene/src/render/water_interaction.ts:708
Texels along each side of the window. The texel size in metres is windowSize over this.
Changing it discards the field.
Returns
number
Set Signature
set resolution(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:711
Parameters
val
number
Returns
void
windowSize
Get Signature
get windowSize():
number
Defined in: libs/scene/src/render/water_interaction.ts:724
Side of the window in metres.
Changing it discards the field.
Returns
number
Set Signature
set windowSize(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:727
Parameters
val
number
Returns
void
texelSize
Get Signature
get texelSize():
number
Defined in: libs/scene/src/render/water_interaction.ts:736
Size of one texel in metres.
Returns
number
waveSpeed
Get Signature
get waveSpeed():
number
Defined in: libs/scene/src/render/water_interaction.ts:747
Speed disturbances spread at, in metres per second.
Capillary ripples run at well under a metre per second, a boat's wake at a few. Clamped to what the explicit scheme can integrate stably on the current texel size: raising resolution or shrinking windowSize lowers that ceiling.
Returns
number
Set Signature
set waveSpeed(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:750
Parameters
val
number
Returns
void
maxWaveSpeed
Get Signature
get maxWaveSpeed():
number
Defined in: libs/scene/src/render/water_interaction.ts:755
Highest wave speed the current window can integrate stably, in metres per second.
Returns
number
damping
Get Signature
get damping():
number
Defined in: libs/scene/src/render/water_interaction.ts:762
Rate the field loses energy at, in 1/s. 0 keeps ripples going until they leave the window; a few damps them within a second or two.
Returns
number
Set Signature
set damping(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:765
Parameters
val
number
Returns
void
foamAmount
Get Signature
get foamAmount():
number
Defined in: libs/scene/src/render/water_interaction.ts:783
How much foam a disturbance throws, 0 to disable the foam trail. Defaults to 0.15: at 1 a wake reads as solid white.
Foam is laid down where something moves through the water, where a stone lands and along the steep, fast crests of the field's own waves, and fades at foamDecay. The material shows it with the same look as the wave generator's crest foam and the shoreline foam.
Returns
number
Set Signature
set foamAmount(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:786
Parameters
val
number
Returns
void
foamDecay
Get Signature
get foamDecay():
number
Defined in: libs/scene/src/render/water_interaction.ts:790
Rate the foam trail fades at, in 1/s.
Returns
number
Set Signature
set foamDecay(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:793
Parameters
val
number
Returns
void
foamThreshold
Get Signature
get foamThreshold():
number
Defined in: libs/scene/src/render/water_interaction.ts:801
How steep and fast a wave of the field has to be before it foams on its own. Lower foams more of the wake; higher keeps foam to what is directly disturbed.
Returns
number
Set Signature
set foamThreshold(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:804
Parameters
val
number
Returns
void
maxAmplitude
Get Signature
get maxAmplitude():
number
Defined in: libs/scene/src/render/water_interaction.ts:807
Returns
number
Set Signature
set maxAmplitude(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:810
Parameters
val
number
Returns
void
spongeWidth
Get Signature
get spongeWidth():
number
Defined in: libs/scene/src/render/water_interaction.ts:818
Width of the absorbing band inside the window edge, as a fraction of the window. Waves reaching it die away instead of reflecting; the material also fades the field out over it so the window has no visible edge.
Returns
number
Set Signature
set spongeWidth(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:821
Parameters
val
number
Returns
void
followMode
Get Signature
get followMode():
WaterInteractionFollowMode
Defined in: libs/scene/src/render/water_interaction.ts:825
How the window is positioned. See WaterInteractionFollowMode.
Returns
Set Signature
set followMode(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:828
Parameters
val
Returns
void
followNode
Get Signature
get followNode():
SceneNode
Defined in: libs/scene/src/render/water_interaction.ts:832
Node the window follows while followMode is node.
Returns
Set Signature
set followNode(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:835
Parameters
val
Returns
void
followNodeId
Get Signature
get followNodeId():
string
Defined in: libs/scene/src/render/water_interaction.ts:843
Persistent id of followNode, for a field loaded from a scene before the node exists. Resolved against the water's scene on the next update; followNode wins when both are set.
Returns
string
Set Signature
set followNodeId(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:846
Parameters
val
string
Returns
void
center
Get Signature
get center():
Vector2
Defined in: libs/scene/src/render/water_interaction.ts:868
World XZ the window is centred on while followMode is fixed.
Returns
Vector2
Set Signature
set center(
val):void
Defined in: libs/scene/src/render/water_interaction.ts:871
Parameters
val
Vector2
Returns
void
originX
Get Signature
get originX():
number
Defined in: libs/scene/src/render/water_interaction.ts:875
World X of the window's low corner, as of the last step.
Returns
number
originZ
Get Signature
get originZ():
number
Defined in: libs/scene/src/render/water_interaction.ts:879
World Z of the window's low corner, as of the last step.
Returns
number
disturbers
Get Signature
get disturbers(): readonly
WaterDisturber[]
Defined in: libs/scene/src/render/water_interaction.ts:908
The disturbers registered with this field.
Returns
readonly WaterDisturber[]
Methods
on()
on<
K>(type,listener,context?):void
Defined in: libs/base/dist/index.d.ts:630
IEventTarget.on
Type Parameters
K
K extends "dispose"
Parameters
type
K
listener
EventListener<{ dispose: []; }, K>
context?
unknown
Returns
void
Inherited from
Disposable.on
once()
once<
K>(type,listener,context?):void
Defined in: libs/base/dist/index.d.ts:634
IEventTarget.once
Type Parameters
K
K extends "dispose"
Parameters
type
K
listener
EventListener<{ dispose: []; }, K>
context?
unknown
Returns
void
Inherited from
Disposable.once
off()
off<
K>(type,listener?,context?):void
Defined in: libs/base/dist/index.d.ts:638
IEventTarget.off
Type Parameters
K
K extends "dispose"
Parameters
type
K
listener?
EventListener<{ dispose: []; }>
context?
unknown
Returns
void
Inherited from
Disposable.off
dispatchEvent()
dispatchEvent<
K>(type, ...args):void
Defined in: libs/base/dist/index.d.ts:642
IEventTarget.dispatchEvent
Type Parameters
K
K extends "dispose"
Parameters
type
K
args
...object[K]
Returns
void
Inherited from
Disposable.dispatchEvent
dispose()
dispose():
void
Defined in: libs/base/dist/index.d.ts:6108
Returns
void
Inherited from
Disposable.dispose
onDispose()
protectedonDispose():void
Defined in: libs/scene/src/render/water_interaction.ts:679
Returns
void
Overrides
Disposable.onDispose
addImpulse()
addImpulse(
x,z,radius,strength):void
Defined in: libs/scene/src/render/water_interaction.ts:904
Push the surface down (or up) at a point, once.
The disturbance is a Gaussian bump added to the field on the next step, so a stone hitting the water is one call, and something dragging through it is a call per frame. Calls beyond what one step can take are carried over to the following step.
Parameters
x
number
World X.
z
number
World Z.
radius
number
Radius of the bump in metres.
strength
number
Peak height of the bump in metres. Negative pushes the surface down, which is what an object entering the water does.
Returns
void
addDisturber()
addDisturber(
disturber):void
Defined in: libs/scene/src/render/water_interaction.ts:915
Register a disturber. Beyond MAX_DISTURBERS enabled disturbers the extra ones are ignored, earliest registered first.
Parameters
disturber
Returns
void
removeDisturber()
removeDisturber(
disturber):void
Defined in: libs/scene/src/render/water_interaction.ts:922
Unregister a disturber.
Parameters
disturber
Returns
void
isOk()
isOk(
device?):boolean
Defined in: libs/scene/src/render/water_interaction.ts:940
Whether the device can host the field: it needs a filterable float or half-float render target.
Parameters
device?
AbstractDevice
Returns
boolean