b3d-water

Water plane with reflections, waves, and underwater fog effect.

Demo

import { b3d, b3dSkybox, b3dWater, b3dReflections, b3dGround, sceneDelta } from 'tosijs-3d'
import { demoSun, orbitCam, spinner } from 'tosijs-3d/demo-utils'

const scene = b3d(
  {
    sceneCreated(el, BABYLON) {
      orbitCam(el, { radius: 24, beta: Math.PI / 2.8, target: [0, 0.4, 0] })
      // crates floating ON the surface (bottom at the water line), bobbing on the swell
      const a = spinner(el, { x: -5, y: 1.0, z: -3, size: 2, spin: 0.12 })
      const b = spinner(el, { x: 4.5, y: 0.7, z: 4, size: 1.4, spin: -0.18 })
      let t = 0
      el.scene.registerBeforeRender(() => {
        t += sceneDelta(el.scene)
        a.position.y = 1.0 + Math.sin(t * 1.1) * 0.14
        b.position.y = 0.7 + Math.sin(t * 1.5 + 1) * 0.14
      })
    },
  },
  demoSun(),
  b3dSkybox({ timeOfDay: 9 }),
  // a textured seafloor, visible through the translucent water — gives the surface real depth
  b3dGround({ y: -1.2, width: 60, height: 60, texture: 'checker', textureTiles: 20, color: '#3a5f6b' }),
  b3dWater({ waterSize: 60, waveHeight: 0.4, windForce: -4, twoSided: true }),
  b3dReflections(),
)
preview.append(scene)
tosi-b3d { width: 100%; height: 100%; }

A lake with a few crates on the shore. The sun rakes across the surface; the water reflects the sky and the crates. Drag to orbit — dip the camera below the surface and the world tints and dims.

Attributes

Attribute Default Description
textureSize 0 (auto) Size of the reflection and refraction textures. Each is the whole scene drawn again. 0 follows the device tier: 1024 / 512 / 256
reflectionRefresh 0 (auto) Redraw those textures every Nth frame. 0 follows the device tier: 1 / 2 / 3. 1 is every frame. It applies in a headset too: one drawing serves both eyes and later frames, looked up through the view it was drawn from
waterSize 128 Size of the water plane
subdivisions 32 Mesh subdivisions
twoSided false Render both sides
underwaterFog 0.12 Fog density the moment the camera is under the surface
underwaterMurk 0.08 Extra fog density at 30 m down: the sea thickens with depth
fogTransition 0.2 Metres below the surface to reach full underwater fog. Tight on purpose, so crossing the surface has no visible jump
underside 'auto' Snell's window from below: straight up, a bright window onto the sky; toward grazing angles, a mirror of the depths. 'auto' = on whenever twoSided; 'on'/'off' force it. Fades in with the underwater fog
fogColor '#00264d' The colour of the water you are IN (the underwater fog). Sea blue by default; a methane sea (Titan) is dark amber
undersideColor '#9fdcf0' The window: the sky's light, looking up
undersideDepthColor '#06283a' The mirror: the dark water, at grazing angles
undersideSky 1 From below, the window REFRACTS THE REAL SKY (the sun included), distorted by the ripples — clearest in the shallows, fading with depth, giving way to the dark mirror toward grazing angles. 0 = the flat undersideColor only
caustics 'auto' Light through the moving surface, dancing on everything beneath it (terrain, hulls, the player). 'auto' = on whenever twoSided. See Caustics below
causticsStrength 0.6 How bright the web gets
causticsScale 6 Metres per caustic cell: bigger is coarser and calmer
shore 'off' 'on' gives the surface the depth of the water under it, from the scene's terrain, and draws a shoreline from it: surf running in, pale shallows, and ice that spreads out from the land when the climate at sea level is below freezing. See Shore and ice below. Not for spherical water. Set at build time
shoreFine false With shore="on": a water vertex every 2 m near the viewer where there is otherwise one every 4 m (about 16,600 vertices, up from 9,400). The surf follows a winding shore more closely; each refresh of the shore data (when the water re-centres, every 32 m travelled) costs about two thirds more. Set at build time
receiveShadows 'on' The surface (and the ice on it) takes shadows from the sun and from clouds. 'off' skips both lookups per water pixel
follow false Ride the camera in x/z (endless sea): the plane snaps to a coarse grid under you, ripples stay anchored in world space
normalMap '' URL of a bump map for the ripples. Empty uses a tiling normal map generated from Perlin noise: no file, no network, so it works offline and in a headset
wind 'scene' 'scene' takes the waves' wind from the scene's wind when it has one; 'own' always uses the three attributes below. A scene with no wind leaves them in charge either way
windForce -5 Wind strength
windDirectionX 0.6 Wind direction, x part (roughly a unit vector with windDirectionY)
windDirectionY 0.8 Wind direction, y part
waveHeight 0 Wave amplitude
waveLength 0.1 Wave length
bumpHeight 0.1 Normal map bump intensity
waterColor '#0066cc' Water tint color
colorBlendFactor 0.1 How much color tints the water
spherical false Use a sphere instead of a plane

Underwater Effect

When the camera goes below the water surface, a blue fog is automatically applied. The sun (if present via b3dSun) is also dimmed based on depth.

import { b3d, b3dWater, b3dSun, b3dSkybox } from 'tosijs-3d'

document.body.append(
  b3d({},
    b3dSun({}),
    b3dSkybox({ timeOfDay: 12 }),
    b3dWater({ y: -0.2, twoSided: true, waterSize: 1024 })
  )
)

Caustics

Light through a moving surface, dancing on what is under it: the strongest "this is underwater" cue after the colour. A material plugin samples a tiling caustic pattern by WORLD position, so it lands on terrain, hulls, the player, anything, with no per-mesh setup. It is drawn only below the water surface, projected along the sun so the pattern slants as the sun does, and it fades with depth and with the fog, because a fully fogged fragment must stay fog. Two layers scroll at different rates and combine with min, which is what makes caustics shimmer rather than slide.

The pattern (causticPattern) is a seeded cellular (Worley) field, bright along the cell edges the way real caustic networks are. Like the normal map it is sampled on a torus, so it tiles exactly by construction. No file, no network.

Shore and ice

With shore="on" each vertex of the water's mesh carries four numbers: the depth of the water there, how much ice covers it, how solid that ice is, and the distance to the waterline. It needs a terrain in the scene to read depths from, and the ice also needs that terrain's biome="on", which is where the temperature comes from. It draws:

Where the ice is

Ice follows the cold and the shore. iceCover(temperature, depth) is the whole rule: nothing above the sea's freezing point (about -2 °C); below it the shallows freeze first and the cover spreads outward into deeper water as it gets colder. So one cold bay has a solid sheet along the beach, breaking into plates further out, and open sea beyond. The temperature is the terrain's climate at sea level INCLUDING the season, so the sea freezes in winter and breaks up in spring.

Cover What is drawn
0 Open water
up to about 0.9 Plates: more of them, and wider, as the cover rises
1 A sheet, with hairline cracks where the plates met

Colder still and the cracks close: iceSolid runs from that cracked sheet to one unbroken surface, shallows first.

Walking on it

Ice is water until it is solid. iceBears is true once the cracks have mostly closed, and there the water carries an invisible collision mesh: the same vertices, only the triangles whose ice bears. Anything that collides or picks meets it like ground, and it is in the ice collision group for anything that wants to tell it from land. Short of solid (plates, or a sheet still showing its cracks) there is nothing there and you fall through and swim. Waves stop under ice, so the sheet is flat where it collides.

A biped swimming at the surface climbs onto solid ice; one that dived first goes under it, with the ice as a ceiling. water.iceBearsAt(x, z) asks the question for a point in the scene.

A mesh that is fine where you are

Depth lives on vertices, so the mesh decides how sharp the shoreline is. The shore grid is a square grid whose lines are close together in the middle (4 m by default) and spread geometrically toward the edge, so a sea 8 km across costs under ten thousand vertices and still has a vertex every few metres around the viewer. shoreFine asks for a finer one: a vertex every 2 m out to 64 m.