Animate a water surface

quick start Intermediate ⏱ 7 min vgai 0.1.0

Prerequisites: Installed vgai and run the editor

What you'll learn

• Run a scene using an ordinary material and a WaterSurface component
• See native BufferGeometry animate in Play mode
• Understand why game-specific visual behavior belongs to the project

What you'll build: A look at the water-shader scene — project-owned water motion in Play mode.

Walkthrough — Animate a water surface · generated by site/media/lessons/scenes-batch.lesson.ts (4 steps)

The legacy filename is water-shader.vscn.json, but the implementation is intentionally ordinary: a standard blue material plus the project’s WaterSurface component. The component animates the mesh’s native vertex positions and recomputes normals each frame.

Follow along in the live web editor

▶ Open the water-shader scene — every step below (including Play) runs right in your browser, no install required.

Steps

1. Open the water-shader scene. The scene is already open — if you followed the link above, the water-shader scene is loaded and rendering (in the local dev editor: VGAI_PROJECT=examples/feature-scenes npm run dev, then open scenes/water-shader.vscn.json).

   

   The water-shader scene.

2. Enter play mode — the WaterSurface component runs. Its init() captures the plane’s base positions; update(dt) applies summed sine waves to the vertices.

   

   The custom Water material.

3. The component displaces native geometry. The scene’s standard material remains ordinary; Play-mode behavior lives in project source and the editor reports zero errors.

   

   Self-animating shader (uTime).

4. Stop play mode. Press Stop (or Escape).

Shaders use the same ownership rule

For a GPU implementation, create THREE.ShaderMaterial directly in the project component and dispose it with the component. Raw GLSL inside .vscn.json is not supported.

Recap

New functionality

• Ran a scene using a project WaterSurface component
• Saw native BufferGeometry animate

New concepts & skills

• The scene keeps an ordinary material
• Game-specific visual behavior belongs to project source
• A component owns init/update/dispose

Next lesson → Manual: Project-owned shaders

On Your Own!

Extend what you built:

• Tweak the component's waveHeight and waveSpeed fields
• Replace vertex motion with a project-owned ShaderMaterial
• Add a second component that pulses emissive intensity

See also

• Custom shaders · Materials