description: WaterExclusion API reference (C++ and Lua) — a volume that keeps water out, like a boat: no water surface, underwater fade, or buoyancy inside it.¶
WaterExclusion¶
Inherits: Object
C++ type: WaterExclusion
Description¶
A volume that keeps Water out, like the inside of a boat. Inside it the water
surface is not drawn, a camera sees no underwater fade, and dynamic
bodies get no buoyancy, so cargo rests on the floor of a boat instead
of floating on the sea outside. Constructing a WaterExclusion attaches a
WaterExclusionComponent to the entity, and the volume moves, rotates, and scales with it.
The default HULL shape wraps the convex hull of the entity's meshes, or of its model's mesh nodes, and is rebuilt when they change. On a boat it is the outer hull closed over the top at the gunwale, so the component goes on the boat itself. BOX and SPHERE fill a volume of their own, for a cabin, a cave, or a diving bell.
A body that owns the volume, on its own entity or on a child of it, still floats: the boat keeps its buoyancy while what it carries loses it. See Rendering Pipeline — Water exclusions for how the surface is cut.
Hidden, on its own entity or through an ancestor, the volume no longer cuts the surface, stops the underwater fade or leaves a wake, and its wake starts afresh when it shows again. Bodies inside it still lose their buoyancy, as hiding leaves physics running.
Properties¶
| Type | Name | Default | Langs |
|---|---|---|---|
| WaterExclusionShape | shape | HULL |
C++ | Lua |
| Vector3 | center | Vector3(0, 0, 0) |
C++ | Lua |
| Vector3 | size | Vector3(1, 1, 1) |
C++ | Lua |
| float | wakeFoam | 0.0 |
C++ | Lua |
| float | wakeWaves | 0.0 |
C++ | Lua |
Methods¶
| Type | Name | Langs |
|---|---|---|
| void | setCenter | C++ | Lua |
| void | setSize | C++ | Lua |
| bool | contains | C++ | Lua |
| WaterExclusionComponent | getWaterExclusionComponent |
Lua |
Enumerations¶
WaterExclusionShape¶
- BOX — A box of size around center.
- SPHERE — An ellipsoid of size around center.
- HULL — The convex hull of the entity's meshes.
Property details¶
shape¶
- Setter: void setShape(WaterExclusionShape shape)
- Getter: WaterExclusionShape getShape() const
A hull is convex, so a boat with a dip in its outline, like a catamaran, takes one volume
per hull, each on its own mesh. Building a hull needs 3D physics, which projects have
unless they turn DORIAX_PHYSICS_3D off (see Build Options).
center / size¶
- Setter: void setCenter(Vector3 center)
- Setter: void setCenter(const float x, const float y, const float z)
- Getter: Vector3 getCenter() const
- Setter: void setSize(Vector3 size)
- Setter: void setSize(const float x, const float y, const float z)
- Getter: Vector3 getSize() const
The box or sphere in the entity's local space: size is its width, height, and depth,
centred on center. A hull ignores them.
wakeFoam / wakeWaves¶
- Setter: void setWakeFoam(float wakeFoam)
- Getter: float getWakeFoam() const
- Setter: void setWakeWaves(float wakeWaves)
- Getter: float getWakeWaves() const
What the volume leaves on a Water while it moves across its surface, from 0
(nothing, the default) to 2. The wake follows the motion of the entity, whatever moves
it — physics, a script or an animation — so a boat only needs these set:
- Foam stays where it forms and fades there: churned behind the stern and, closer to hull speed, along the sides and at the bow, where the bow waves of a fast hull break.
- Waves spread from where the bow passed, at the Kelvin angle of 19.5° on each side, narrowing past a length Froude number of about 0.5, with the transverse waves crossing between them. They bend the surface, so they show in its light and reflections.
Both grow with the speed relative to the hull speed of the volume's length, so a small boat drifting leaves almost nothing and one near its hull speed a full wake. The water keeps the wakes in a square around the camera and fades them over its wakeFade. Waves stay on the water they were made on, even after the volume leaves it. The waterline is taken as an ellipse inside the volume's bounds, facing the motion.
The wake is drawn by the built-in water shader; a fork of an older version draws none until it is forked again.
Method details¶
contains¶
- bool contains(Vector3 point) const
Whether the world point is inside the volume, tested as buoyancy tests it. Gameplay that should agree with the water, like the air of a diver, can use it:
The volume is placed by the render update, so a new one contains nothing until the next frame.