Three Vue3Three Vue3
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
Guide
Demo
AI Agents
  • English
  • 简体中文
GitHub
    • Getting Started
    • Scene
    • Parameter Bus
    • SkyBox
    • Model Loader

      • Component Loader
      • Function Loader
    • Popup
    • Callout
    • Movable Element
    • Animation
    • Model Rotator
    • Picker
    • Fit Camera
    • Mesh

      • Wave Circle Mesh
      • Flow Line Mesh
    • Effect

      • Nature

        • Rain
        • Snow
        • Water
        • Water Pool
          • Default Usage
          • Irregular Pool
          • Props
          • How It Works
          • Renderer Support
        • Sandy Beach
      • Sky & Atmosphere

        • Sky Dome
        • HeightFog
        • Nebula Galaxy
      • Light

        • Bloom
        • Sweep Light
        • Light Gradient
        • Light Pillar
        • Radar Sweep
        • Signal Wave
        • Force Shield
      • Particles & Sprites

        • Fireworks
        • Text Fireworks
        • Glow Sprite
    • GIS

      • Geographic Reference
      • GeoObject
      • GeoJsonLayer
      • Tile Layer

type

Component

<tv-water-pool> renders an interactive, ray-traced water pool inside a <tv-scene>. It is a port of Evan Wallace's webgl-water and the WaterPool component from react-three-lite.

A CPU height field drives the ripples and caustic light map, which are uploaded as data textures. The water surface, tiled basin, and procedural sky are shaded by analytical rays in the fragment shader, so WebGPU and WebGL show the same reflection, refraction, and caustic result without extra scene captures.

Default Usage

Click me to view the pool setup
<template>
  <tv-scene
    class="scene"
    bg-color="rgb(40, 42, 54)"
    :axes-helper="false"
    :grid-helper="false"
    @created="created"
  >
    <tv-water-pool :shape="WATER_OUTLINE" :scale="WATER_SCALE" />
  </tv-scene>
</template>

<script lang="ts" setup>
import * as THREE from 'three'
import { globalParameterBus } from 'three-vue3'
import type { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js'

const WATER_SCALE = 0.7
const TUB_SCALE: [number, number, number] = [1.59, 1.15, 0.868]
const WATER_HALF_X = (0.33 * TUB_SCALE[0] + 0.02) / WATER_SCALE
const WATER_HALF_Z = (0.72 * TUB_SCALE[2] + 0.02) / WATER_SCALE
const WATER_OUTLINE: [number, number][] = [
  [-WATER_HALF_X, -WATER_HALF_Z],
  [WATER_HALF_X, -WATER_HALF_Z],
  [WATER_HALF_X, WATER_HALF_Z],
  [-WATER_HALF_X, WATER_HALF_Z]
]

const created = (
  _scene: THREE.Scene,
  { camera, controls }: { camera?: THREE.Camera; controls?: OrbitControls }
) => {
  globalParameterBus.set('sunDirection', new THREE.Vector3(0.55, 0.9, 0.35))
  if (!camera) return
  camera.position.set(1.75, 2.2, 2.0)
  if (controls) controls.target.set(0, 0, 0)
  camera.lookAt(0, 0, 0)
}
</script>

The live demo loads /models/water-tub.glb without Draco at scale [1.59, 1.15, 0.868] and position [0, 0.09 - 0.53 * 1.15, 0]. Its SkyDome uses horizon 0x94c2f0, lower sky 0x7fb4ec, upper sky 0x3d7bd5, zenith 0x296bc7, glow 0xfff1d8, sun 0xfff7e6, intensity 2.2, and sun size 5, with the default radius 420 and 48 segments. Models, the dome, and late asynchronous loads are disposed on scene teardown.

Drag the water to add ripples; drag outside it to orbit the camera.

Irregular Pool

Click me to view the shaped-pool setup
<tv-water-pool :shape="TUB_OUTLINE" :scale="0.536 * 1.7" :position="[0, 0.33 * 1.7, 0]" />

<script lang="ts" setup>
const TUB_OUTLINE: [number, number][] = [
  [-1, 0],
  [-0.987, -0.106],
  [-0.945, -0.207],
  [-0.879, -0.291],
  [-0.795, -0.358],
  [-0.694, -0.399],
  [-0.588, -0.412],
  [0.513, -0.412],
  [0.619, -0.399],
  [0.72, -0.358],
  [0.804, -0.291],
  [0.871, -0.207],
  [0.981, -0.028],
  [0.981, 0.028],
  [0.871, 0.207],
  [0.804, 0.291],
  [0.72, 0.358],
  [0.619, 0.399],
  [0.513, 0.412],
  [-0.588, 0.412],
  [-0.694, 0.399],
  [-0.795, 0.358],
  [-0.879, 0.291],
  [-0.945, 0.207],
  [-0.987, 0.106]
]
</script>

The camera is [1.7, 1.35, 1.9], targeting [0, 0.3, 0], with background rgb(40, 42, 54) and axes/grid helpers disabled. This demo uses the same sun direction and SkyDome configuration as the default pool. /models/bathtub.glb is loaded without Draco at uniform scale 1.7 and position [-0.595 * 1.7, 0, 0.28 * 1.7].

Props

NameTypeDefaultDescription
resolutionnumber128optional Height-field cells per axis, clamped to 8–512.
shape'box' | WaterPoolOutline | BufferGeometryWATER_POOL_IRREGULAR_CUBE_OUTLINEoptional Built-in square, custom convex outline, or geometry projected onto XZ.
segmentsnumber160optional Subdivisions around the resolved container outline.
autoRipplesbooleantrueoptional Adds a small random ripple every 1.8 seconds.
interactivebooleantrueoptional Enables dragging the water surface to create drops.
positionVector3 | [number, number, number][0, 0, 0]optional World position of the water surface center.
scalenumber1optional Positive uniform scale applied to both the footprint and pool depth.
type WaterPoolOutline = readonly (readonly [number, number])[]

shape="box" resolves to WATER_POOL_BOX_OUTLINE, a square with x and z from -1 to 1. The default WATER_POOL_IRREGULAR_CUBE_OUTLINE is a skewed quadrilateral. Custom outlines and geometry vertices are reduced to a convex hull with collinear points removed; the result must contain the origin and stay within -1…1. Both built-in outlines are exported for reuse.

The component follows globalParameterBus for its sun direction; it does not expose the former local explicit-sun, box, sky, curvature, or edge-width props. Pointer rays and drops are transformed into pool-local coordinates, so interaction remains aligned after position and scale changes.

How It Works

  • A CPU height field stores (height, velocity, normal.x, normal.z) per cell and runs the two-pass wave equation. The state is uploaded as an RGBA half-float DataTexture and displaces the water surface in the vertex node.
  • The caustic map projects surface cells onto the pool floor along their refracted sun rays. Local compression of the projection concentrates light into animated caustics.
  • The single water surface uses analytical ray tracing in TSL to reflect and refract the tiled basin and procedural sky, including the pool walls and floor.
  • Dragging the water adds drops to the height field, producing propagating wakes while preserving orbit-control handoff outside the pool.
  • The simulation runs on a fixed 1/60 s accumulator with at most three catch-up steps per frame, so ripples behave consistently across display refresh rates.

The tile texture is generated in a canvas, so the component itself downloads no assets. The GLBs in these examples are demo scenery only. Replaced geometry, materials, textures, listeners, animation callbacks, and subscriptions are disposed on rebuild and unmount.

Renderer Support

All shading is written with TSL node materials, so the same effect runs on both renderers:

  • WebGPU executes the node graph directly with WebGPURenderer.
  • WebGL compiles the same TSL graph to GLSL through WebGLNodesHandler.
Edit this page on GitHub
Last Updated:
Contributors: Shing Rui, ruixinglong
Prev
Water
Next
Sandy Beach