Stylized Water Shader

Drop it into your project

1. Copy stylized_water.gdshader, stylized_water.gdshader.uid, water_material.tres, both normal map PNGs and their .import files into your project, for example into res://water/. The .import files carry the normal map import settings, and the material finds the shader by the ID in the .uid file.
2. Add a MeshInstance3D and give it a new PlaneMesh. Set its Size to the area of water you need, then set Subdivide Width and Subdivide Depth so the vertices are about 0.25 m apart. A 48 m plane needs 191, which is what the demo uses. The pitfalls below explain the number.
3. Drag water_material.tres into the MeshInstance3D's Surface Material Override slot. Leave the node's rotation at 0 and its scale at 1, and move it up or down to set the water level. To make the water bigger, change the PlaneMesh Size rather than the node's scale.
4. Make sure there is opaque geometry under and through the water: a sea floor, a shore, rocks, posts. The depth colour and the foam are measured against those surfaces. Where there is nothing under the water, it shows deep_color.
5. Give the scene a WorldEnvironment with a sky and a DirectionalLight3D. The bright streaks on the waves are the sky reflected in them and the sparkles are the sun, so the water needs both to show its ripples.
6. Tune the look under the material's Shader Parameters. Every water plane that uses the same .tres shares the settings. For a pond and a sea with different colours, duplicate the material.

Parameters

How it works

render_mode blend_mix, depth_draw_opaque, cull_back, diffuse_burley, specular_schlick_ggx;

uniform sampler2D depth_texture : hint_depth_texture, repeat_disable, filter_nearest;

float raw_depth = textureLod(depth_texture, SCREEN_UV, 0.0).r;

#if CURRENT_RENDERER == RENDERER_COMPATIBILITY
	vec3 ndc = vec3(SCREEN_UV, raw_depth) * 2.0 - 1.0;
#else
	vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, raw_depth);
#endif
	vec4 behind_view = INV_PROJECTION_MATRIX * vec4(ndc, 1.0);
	behind_view.xyz /= behind_view.w;
	vec3 behind_world = (INV_VIEW_MATRIX * vec4(behind_view.xyz, 1.0)).xyz;
	vec3 surface_world = (INV_VIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
	float water_depth = max(surface_world.y - behind_world.y, 0.0);

float edge = foam_width > 0.0 ? 1.0 - clamp(water_depth / foam_width, 0.0, 1.0) : 0.0;
float threshold = clamp(0.5 + 0.35 * (ripple_a.x + ripple_b.y), 0.05, 0.95);
float foam = smoothstep(threshold - 0.06, threshold + 0.06, edge);

height += amplitude * sin(phase);
slope += amplitude * cos(phase) * k * WAVE_DIR[i];

// in vertex():
NORMAL = normalize(vec3(-slope.x, 1.0, -slope.y));
TANGENT = normalize(vec3(TANGENT.x, dot(TANGENT.xz, slope), TANGENT.z));
BINORMAL = normalize(vec3(BINORMAL.x, dot(BINORMAL.xz, slope), BINORMAL.z));

// Stylized Water
// Depth-tinted water with foam where it meets objects, moving normal maps and
// vertex waves.
// Godot 4.7 · CC0 1.0 · godotlearning.com/shaders/stylized-water
shader_type spatial;
// blend_mix: ALPHA is transparency. depth_draw_opaque: depth is written for
// opaque surfaces only, and writing ALPHA makes this one transparent, so the
// water writes no depth. cull_back: the underside is not drawn. diffuse_burley
// and specular_schlick_ggx are Godot's default lighting models.
render_mode blend_mix, depth_draw_opaque, cull_back, diffuse_burley, specular_schlick_ggx;

// Colour where the water is shallow. Alpha is how opaque it is there.
uniform vec4 shallow_color : source_color = vec4(0.24, 0.8, 0.76, 0.45);
// Colour where the water is depth_distance metres deep or more.
uniform vec4 deep_color : source_color = vec4(0.02, 0.17, 0.33, 0.94);
// Metres of water (measured straight down) over which the colour goes from
// shallow_color to deep_color.
uniform float depth_distance : hint_range(0.1, 10.0) = 2.0;
// Colour of the foam. Alpha is how opaque the foam is.
uniform vec4 foam_color : source_color = vec4(0.96, 0.98, 1.0, 1.0);
// Metres of water depth that still get foam. 0 turns foam off.
uniform float foam_width : hint_range(0.0, 1.0) = 0.2;
// How high a crest can rise above the plane, in metres. 0 turns waves off.
uniform float wave_height : hint_range(0.0, 1.0) = 0.1;
// Length of the longest wave in metres. The other three are shorter.
uniform float wave_length : hint_range(0.5, 20.0) = 4.0;
// Speed of the waves and of the normal map scroll. 0 freezes the water. The
// 0.01 step stops the water jumping when TIME wraps round after an hour.
uniform float wave_speed : hint_range(0.0, 2.0, 0.01) = 0.5;
// Two tileable normal maps, scrolled in different directions and added.
uniform sampler2D normal_map_a : hint_normal, filter_linear_mipmap, repeat_enable;
uniform sampler2D normal_map_b : hint_normal, filter_linear_mipmap, repeat_enable;
// Strength of the small ripples from the normal maps. 0 leaves only the waves.
uniform float normal_scale : hint_range(0.0, 2.0) = 0.25;
// Metres covered by one tile of normal_map_a. normal_map_b tiles twice as often.
uniform float normal_tile_size : hint_range(0.5, 50.0) = 8.0;
// Surface roughness of the water. Low values give a small, sharp sun glint.
uniform float roughness : hint_range(0.0, 1.0) = 0.06;

// The depth buffer of everything opaque drawn before the water.
uniform sampler2D depth_texture : hint_depth_texture, repeat_disable, filter_nearest;

// Four sine waves: direction (unit vector), length as a fraction of
// wave_length, share of wave_height, and how many half turns each makes per
// unit of TIME * wave_speed. Whole numbers of half turns make every wave repeat
// after 2 units, which is 4 seconds at the default wave_speed of 0.5.
const vec2 WAVE_DIR[4] = vec2[4](
	vec2(0.958, 0.287), vec2(-0.447, 0.894), vec2(0.6, -0.8), vec2(-0.894, -0.447)
);
const float WAVE_LENGTH[4] = float[4](1.0, 0.71, 0.53, 0.37);
const float WAVE_SHARE[4] = float[4](0.4, 0.27, 0.2, 0.13);
const float WAVE_HALF_TURNS[4] = float[4](1.0, 2.0, 2.0, 3.0);

varying vec2 world_xz;

// Height of the surface at a world position, and its slope along x and z.
vec3 waves(vec2 xz, float t) {
	float height = 0.0;
	vec2 slope = vec2(0.0);
	for (int i = 0; i < 4; i++) {
		float k = TAU / (wave_length * WAVE_LENGTH[i]);
		float phase = k * dot(WAVE_DIR[i], xz) - PI * WAVE_HALF_TURNS[i] * t;
		float amplitude = wave_height * WAVE_SHARE[i];
		height += amplitude * sin(phase);
		// d/dx and d/dz of amplitude * sin(phase): the chain rule gives
		// amplitude * cos(phase) * k * direction.
		slope += amplitude * cos(phase) * k * WAVE_DIR[i];
	}
	return vec3(height, slope);
}

void vertex() {
	// Waves are placed in world space, so tiles of water side by side line up.
	vec3 world = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
	world_xz = world.xz;
	vec3 wave = waves(world.xz, TIME * wave_speed);
	VERTEX.y += wave.x;
	// The surface y = h(x, z) has the normal (-dh/dx, 1, -dh/dz). Tangent and
	// binormal tilt by the slope along their own direction, so normal mapping
	// follows the waves.
	vec2 slope = wave.yz;
	NORMAL = normalize(vec3(-slope.x, 1.0, -slope.y));
	TANGENT = normalize(vec3(TANGENT.x, dot(TANGENT.xz, slope), TANGENT.z));
	BINORMAL = normalize(vec3(BINORMAL.x, dot(BINORMAL.xz, slope), BINORMAL.z));
}

void fragment() {
	float t = TIME * wave_speed;

	// Ripples: two normal maps scrolling in different directions. Each moves a
	// whole number of tiles every 2 units of t, so the scroll loops with the waves.
	vec2 uv = world_xz / normal_tile_size;
	vec2 uv_a = uv + vec2(0.5, 0.0) * t;
	vec2 uv_b = uv * 2.0 + vec2(-0.5, 0.5) * t;
	vec2 ripple_a = texture(normal_map_a, uv_a).rg * 2.0 - 1.0;
	vec2 ripple_b = texture(normal_map_b, uv_b).rg * 2.0 - 1.0;
	// Adding the x and y slopes of two normal maps blends them; Godot rebuilds
	// the blue channel from x and y.
	vec2 ripple = ripple_a + ripple_b;
	ripple /= max(1.0, length(ripple) / 0.95);

	// Depth: rebuild the position of whatever opaque surface is behind this
	// pixel, then measure how far below the water surface it is.
	float raw_depth = textureLod(depth_texture, SCREEN_UV, 0.0).r;
#if CURRENT_RENDERER == RENDERER_COMPATIBILITY
	// OpenGL (Compatibility): NDC depth runs from -1 to 1.
	vec3 ndc = vec3(SCREEN_UV, raw_depth) * 2.0 - 1.0;
#else
	// Vulkan (Forward+ and Mobile): NDC depth runs from 0 to 1.
	vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, raw_depth);
#endif
	vec4 behind_view = INV_PROJECTION_MATRIX * vec4(ndc, 1.0);
	behind_view.xyz /= behind_view.w;
	vec3 behind_world = (INV_VIEW_MATRIX * vec4(behind_view.xyz, 1.0)).xyz;
	vec3 surface_world = (INV_VIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
	float water_depth = max(surface_world.y - behind_world.y, 0.0);

	// Colour: shallow to deep over depth_distance metres.
	vec4 water = mix(shallow_color, deep_color, clamp(water_depth / depth_distance, 0.0, 1.0));

	// Foam: 1 where the water touches something, 0 at foam_width metres deep.
	// A threshold taken from the ripples breaks the band into moving patches.
	float edge = foam_width > 0.0 ? 1.0 - clamp(water_depth / foam_width, 0.0, 1.0) : 0.0;
	float threshold = clamp(0.5 + 0.35 * (ripple_a.x + ripple_b.y), 0.05, 0.95);
	float foam = smoothstep(threshold - 0.06, threshold + 0.06, edge);

	ALBEDO = mix(water.rgb, foam_color.rgb, foam);
	ALPHA = mix(water.a, foam_color.a, foam);
	ROUGHNESS = mix(roughness, 0.9, foam);
	SPECULAR = 0.5;
	NORMAL_MAP = vec3(ripple * 0.5 + 0.5, 1.0);
	NORMAL_MAP_DEPTH = normal_scale * (1.0 - foam);
}

Pitfalls and renderer notes

• Foam forms around rocks but not around a glass bottle, a particle effect or another water plane. The depth texture only holds opaque surfaces, so anything transparent is invisible to it. Give an object an opaque material, or an opaque stand-in mesh hidden inside it, if the water should foam around it. In a test with ALPHA removed so the water itself was opaque, the tint and foam still worked on all three renderers, but nothing under the water showed through.
• Smoke, glass or particles near the water show on the wrong side of it. The water writes no depth, so Godot orders it against other transparent objects by their distance from the camera, and a big plane's distance is measured to its centre, far from most of its surface. In a test from the demo's camera, a see-through red quad 1.5 m above the water but 26 m away was drawn under the water, whose centre was 15 m away. A quad 1.2 m under the water and about 10 m away was drawn on top of it. Both happened on all three renderers. The fix is render_priority on the materials: the docs say higher priority draws on top. With the water left at 0, setting the above-water quad's material to 1 and the under-water quad's to -1 put both on the right side on all three renderers. Setting the water to -1 fixed the quad above but not the one under. sorting_offset on the quad's node also works, but it has to beat the gap in distance: 20 fixed the 11 m gap and 5 did not.
• The water disappears when the camera goes under it. cull_back skips the underside, so from below you see the sky. Setting cull_disabled draws the underside, but the depth is then measured upwards and clamps to 0, and in a test the whole underside came out as a flat, pale sheet. Under-water views need their own effect, such as a tint or fog that turns on while the camera is below the water level.
• The water looks wrong on a rotated or scaled node. The shader works out the waves in world space and writes them into the mesh's own space, and those match only while the node has no rotation and a scale of 1. Resize the water with the PlaneMesh Size, not the node's scale.
• Too few subdivisions. A wave needs several vertices along its length to keep its shape. At the defaults the shortest wave is 1.48 m long, and the demo's 0.25 m spacing gives it about six vertices. In a test with 1 m spacing (47 subdivisions on the 48 m plane) and taller waves, the surface turned into flat-sided lumps and the short waves vanished. If you lengthen wave_length, you can use fewer subdivisions.
• Too many subdivisions. A PlaneMesh with n subdivisions has (n + 1)² quads, so the count grows fast: 47 gives 4,608 triangles, 191 gives 73,728, 479 gives 460,800 and 959 gives 1,843,200. On an RTX 3060 at 1280 by 720, the demo's water cost about 0.23, 0.29, 0.43 and 0.76 ms of GPU time at those four sizes under Forward+, and 0.16, 0.25, 0.37 and 1.40 ms under Compatibility. A phone has far less to spare, so measure on the device. For a big sea, use several water planes side by side with the same vertex spacing. The waves are worked out in world space, so the shared edges match: in a test, two 12 m planes with 0.25 m spacing gave the same wave surface, vertex for vertex, as one 24 m plane. Planes with different spacing do not match. The coarse edge runs straight between its vertices while the fine one follows the waves, and in a test with 0.25 m next to 1 m spacing, thin gaps opened along the seam at the default wave_height. If you want coarser water far away, put the change of spacing where opaque geometry, such as a shore or a line of rocks, covers the seam.
• Very large worlds. Godot uses 32-bit floats, which can step about 1 mm at 10 km from the origin and about 8 mm at 100 km. In a test with the whole demo moved 100 km along x and the waves, ripples and foam turned off, only scattered pixels along the edges of objects changed. Precision is not the first limit for water; the vertex count of a huge plane is.
• Shadows. The docs say transparent materials cannot cast shadows, so the water never shades the sea floor. It does receive them: in a test the jetty's shadow fell on the water on all three renderers. The demo's sun has shadows off for another reason. Under Compatibility, turning them on made the sand and rocks much brighter, with the sand blowing out to white, while Forward+ and Mobile did not change. A grey plane in a minimal scene showed the same, 143 instead of 125 out of 255, only when the light cast shadows and ambient light was on. Check your lighting under Compatibility if you target the web.
• The colours differ under Compatibility. The tint and foam land in the same places on all three renderers, but Compatibility shows deeper blues and a little less of what is under shallow water. The renderer notes below have the numbers. Tune shallow_color and deep_color while running in the renderer you ship with.
• The ripples look wrong after you swap in your own normal map. Godot expects OpenGL-style normal maps, with green pointing up. A DirectX-style map from another tool needs Normal Map Invert Y turned on in its import settings. Set Compress > Normal Map to Enable too: with the default Detect, the editor only switches it once it sees the texture used as a normal map.

The demo scene was run under Forward+, Mobile and Compatibility with no errors or warnings. The depth maths has a branch for Compatibility, whose OpenGL depth range differs from the Vulkan one Forward+ and Mobile use. In a test that painted the water in bands at 0.2, 1 and 2 m of depth, the bands matched Forward+ on all but 12 of 587,751 water pixels under Mobile and 22 under Compatibility, so the tint and foam sit in the same places on all three. Mobile also looks the same as Forward+. Compatibility turns the same shader output into slightly different colours: the deep water is a stronger blue, the middle depths are bluer and shapes under shallow water show a little less. The difference stays with the water set to unshaded, so it is not the lighting or the depth read. If you ship a web build, which uses Compatibility, tune the colours while running in Compatibility.

Pairs with

Learn the idea behind it

• Godot 3D Lighting and Materials: Make a Small Scene Read Clearly

More free shaders

Questions

How do I make foam where water touches objects in Godot 4?

Read the depth buffer in the water shader with a sampler2D that has the hint_depth_texture hint. Turn the depth behind each water pixel back into a world position with INV_PROJECTION_MATRIX and INV_VIEW_MATRIX, subtract its height from the water surface's height, and draw foam where the difference is small. Write ALPHA so the water is drawn as transparent, after the opaque objects, and you can see the bottom through it. This shader does exactly that, with the code for each step on this page.

Why is my water depth wrong in the Compatibility renderer?

Compatibility runs on OpenGL, where the depth in normalized device coordinates goes from -1 to 1, while Forward+ and Mobile use Vulkan's 0 to 1. Convert the depth with * 2.0 - 1.0 under Compatibility only, using #if CURRENT_RENDERER == RENDERER_COMPATIBILITY. With that branch, this shader put its depth bands in the same places on all three renderers to within 22 pixels.

Does this water shader work on mobile and in web exports?

Yes. The demo runs with no errors under Forward+, Mobile and Compatibility, which is the renderer web exports use. Mobile looks the same as Forward+. Compatibility puts the foam and tint in the same places but shows slightly deeper blues. Cost grows with the number of vertices in the water plane, so keep the subdivisions as low as your waves allow on a phone.

Why does my water plane look flat even though the waves move?

Moving VERTEX.y changes the shape but not the lighting, which follows NORMAL. Work out the slope of your waves in vertex() and set NORMAL to normalize(vec3(-dh/dx, 1.0, -dh/dz)). Tilt TANGENT and BINORMAL by the same slopes if you also use a normal map. Also check the plane has enough subdivisions: a plane with none has only four corners to move.