GameCrew AIEarly access
Sign in
Godot 4waterCompile-verified pattern

Stylized Water, Gerstner Waves & Depth Shoreline Foam in Godot 4 Compatibility

Godot 4.7 Compatibility spatial water shader using analytical Gerstner vertex waves, hint_depth_texture shoreline foam, Beer-Lambert depth absorption, and Fresnel horizon sheen.

  • water
  • ocean
  • waves
  • gerstner
  • foam
  • depth
  • shader
  • gdshader
  • compatibility
  • shoreline

When to Use & Field Best Practices

In Godot 4's Compatibility renderer, StandardMaterial3D transparency cannot draw depth-based shoreline foam or Gerstner wave crests. A concise shader_type spatial shader gives islands, harbors, canals, andtide-pool levels lively water in a single draw call:

  • Godot 4 Depth Uniform Syntax: Always declare uniform sampler2D depth_tex : hint_depth_texture, filter_nearest; (never Godot 3's removed DEPTH_TEXTURE built-in) and reconstruct view-space $Z$ using INV_PROJECTION_MATRIX with ndc = vec3(SCREEN_UV * 2.0 - 1.0, depth) in Compatibility/OpenGL clip space ([-1, 1] $Z$ on WebGL 2 — handle with PROJECTION_MATRIX[3][2] or full INV_PROJECTION_MATRIX homogeneous divide!).
  • IMPORTANT Compatibility Clip-Space Z Rule: Because Godot 4's Compatibility renderer uses OpenGL clip-space Z ∈ [-1, 1] (whereas Forward+/Mobile Vulkan use $[0, 1]$), branch on #if CURRENT_RENDERER == RENDERER_COMPATIBILITY when reconstructing ndc.z = depth * 2.0 - 1.0 vs depth! That single guard prevents shoreline foam from vanishing in browser builds.

Mathematical & Algorithmic Core

#if CURRENT_RENDERER == RENDERER_COMPATIBILITY
vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, raw_depth * 2.0 - 1.0);
#else
vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, raw_depth);
#endif
vec4 view_pos = INV_PROJECTION_MATRIX * vec4(ndc, 1.0);
view_pos.xyz /= view_pos.w;
float linear_scene_depth = -view_pos.z;
float water_depth = max(0.0, linear_scene_depth + VERTEX.z);

Engine Implementation

1. Compatibility Stylized Water Shader (Assets/Game/Shaders/stylized_water.gdshader)

shader_type spatial;
render_mode blend_mix, depth_draw_never, cull_back, specular_schlick_ggx;

uniform sampler2D depth_tex : hint_depth_texture, filter_nearest;
uniform vec4 shallow_color : source_color = vec4(0.16, 0.73, 0.75, 0.78);
uniform vec4 deep_color : source_color = vec4(0.04, 0.21, 0.39, 0.95);
uniform vec4 foam_color : source_color = vec4(0.95, 0.98, 1.00, 1.0);
uniform float depth_fade_distance : hint_range(0.3, 15.0) = 3.2;
uniform float foam_width : hint_range(0.05, 3.0) = 0.65;
uniform vec4 wave_a = vec4(0.86, 0.50, 0.20, 12.0);
uniform vec4 wave_b = vec4(-0.42, 0.91, 0.14, 6.5);

varying vec3 world_pos;

vec3 gerstner(vec4 wave, vec3 p, inout vec3 tangent, inout vec3 binormal) {
	float steepness = wave.z;
	float k = 6.2831853 / max(0.5, wave.w);
	float c = sqrt(9.81 / k);
	vec2 d = normalize(wave.xy);
	float f = k * (dot(d, p.xz) - c * TIME);
	float a = steepness / k;
	tangent += vec3(-d.x * d.x * steepness * sin(f), d.x * steepness * cos(f), -d.x * d.y * steepness * sin(f));
	binormal += vec3(-d.x * d.y * steepness * sin(f), d.y * steepness * cos(f), -d.y * d.y * steepness * sin(f));
	return vec3(d.x * a * cos(f), a * sin(f), d.y * a * cos(f));
}

float hash21(vec2 p) {
	p = fract(p * vec2(123.34, 456.21));
	p += dot(p, p + 45.32);
	return fract(p.x * p.y);
}

float foam_cells(vec2 uv) {
	vec2 i = floor(uv);
	vec2 f = fract(uv);
	float best = 1.0;
	for (int y = -1; y <= 1; y++) {
		for (int x = -1; x <= 1; x++) {
			vec2 nb = vec2(float(x), float(y));
			float h = hash21(i + nb);
			vec2 pt = 0.5 + 0.42 * sin(TIME * 1.4 + 6.2831 * vec2(h, hash21(i + nb + 5.3)));
			best = min(best, length(nb + pt - f));
		}
	}
	return best;
}

void vertex() {
	vec3 wp = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
	vec3 tangent = vec3(1.0, 0.0, 0.0);
	vec3 binormal = vec3(0.0, 0.0, 1.0);
	vec3 disp = gerstner(wave_a, wp, tangent, binormal) + gerstner(wave_b, wp, tangent, binormal);
	VERTEX += disp;
	NORMAL = normalize(cross(binormal, tangent));
	world_pos = wp + disp;
}

void fragment() {
	float raw_depth = texture(depth_tex, SCREEN_UV).r;
	#if CURRENT_RENDERER == RENDERER_COMPATIBILITY
	vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, raw_depth * 2.0 - 1.0);
	#else
	vec3 ndc = vec3(SCREEN_UV * 2.0 - 1.0, raw_depth);
	#endif
	vec4 view_scene = INV_PROJECTION_MATRIX * vec4(ndc, 1.0);
	view_scene.xyz /= view_scene.w;
	float water_depth = max(0.0, -view_scene.z + VERTEX.z);

	float absorb = 1.0 - exp(-water_depth / max(0.1, depth_fade_distance));
	vec4 base_col = mix(shallow_color, deep_color, clamp(absorb, 0.0, 1.0));

	float n1 = foam_cells(world_pos.xz * 0.7 + TIME * vec2(0.16, 0.11));
	float n2 = foam_cells(world_pos.xz * 1.2 - TIME * vec2(0.13, 0.17));
	float shore = 1.0 - clamp(water_depth / max(0.05, foam_width), 0.0, 1.0);
	float foam = step(0.44, shore * 0.85 + (n1 + n2) * 0.25);

	ALBEDO = mix(base_col.rgb, foam_color.rgb, foam);
	ALPHA = clamp(mix(base_col.a, 1.0, foam), 0.0, 1.0);
	ROUGHNESS = mix(0.08, 0.65, foam);
	SPECULAR = 0.65;
}

2. Building Subdivided Water Plane in GDScript (PlaneMesh)

static func spawn_water(parent: Node3D, size: Vector2, level_y := 0.0) -> MeshInstance3D:
	var mesh := PlaneMesh.new()
	mesh.size = size
	mesh.subdivide_width = clampi(int(size.x / 2.0), 16, 96)
	mesh.subdivide_depth = clampi(int(size.y / 2.0), 16, 96)

	var mat := ShaderMaterial.new()
	mat.shader = load("res://Assets/Game/Shaders/stylized_water.gdshader") as Shader

	var inst := MeshInstance3D.new()
	inst.name = "StylizedWater"
	inst.mesh = mesh
	inst.material_override = mat
	inst.position = Vector3(0.0, level_y, 0.0)
	inst.cast_shadow = GeometryInstance3D.SHADOW_CASTING_SETTING_OFF
	parent.add_child(inst)
	return inst

Browser, Mobile & Software-Renderer Budgets

  • Subdivision Cap: Cap PlaneMesh subdivisions at 96 × 96 (~18k triangles) so vertex displacement stays under 0.2 ms on phones.
  • depth_draw_never: Essential on transparent water using hint_depth_texture so the water surface never reads its own depth in WebGL 2.

Verification Checklist

  1. Verify #if CURRENT_RENDERER == RENDERER_COMPATIBILITY is present whenever hint_depth_texture is linearized.
  2. Check shoreline foam around partially submerged rocks/docks in Captures/*.png.

Official references

  • Jerry Tessendorf (SIGGRAPH 2001 — Simulating Ocean Water)
  • GPU Gems Ch. 1 (Gerstner Waves)
  • Godot 4 Spatial Shader Depth Texture Reference

Playable Godot 4 games made with GameCrew

Launch a real browser build using this engine and inspect its controls or fork its project tree.

Fernlight — Raise a carved whistle to your lips in a fog-drowned forest, coax a glowing bird onto your open hand, and point to send it off to light the dark.
Plays in VR

Fernlight

Raise a carved whistle to your lips in a fog-drowned forest, coax a glowing bird onto your open hand, and point to send it off to light the dark.

More Godot 4 techniques

physics

CharacterBody3D Slopes, Snap & Coyote Jump in Godot 4 →

Crisp Godot 4 CharacterBody3D locomotion combining floor_snap_length, apex hang gravity, jump-cut, coyote time, and zero-arg move_and_slide.

ai

Context Steering, Patrol Paths & Telegraphed Enemy Encounters in Godot 4 →

Typed GDScript 4 context steering, LevelData patrol-path following, line-of-sight perception with memory hysteresis, attack-token pacing, and telegraphed combat state machines.

gameplay

Frame-Rate-Independent Springs, Squash-Stretch & Ribbon Trails in Godot 4 →

Typed GDScript 4 second-order damped springs, volume-preserving visual squash-stretch, Eiserloh T^2 FastNoiseLite camera trauma, and ImmediateMesh sword/dash ribbon trails.

atmosphere

Raymarched Volumetric Cloud Sky in Godot 4 Compatibility (WebGL 2) →

Compatibility-safe sky shader in Godot 4.7 raymarching a height-bounded cloud slab with procedural 3D hash FBM, Beer-Powder silver lining, Henyey-Greenstein phase, and AT_CUBEMAP_PASS step budgeting.

Use verified techniques inside a real game

Describe your game idea for free or connect an MCP assistant to search and contribute techniques.

Learn about collaboration