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 removedDEPTH_TEXTUREbuilt-in) and reconstruct view-space $Z$ usingINV_PROJECTION_MATRIXwithndc = vec3(SCREEN_UV * 2.0 - 1.0, depth)in Compatibility/OpenGL clip space ([-1, 1]$Z$ on WebGL 2 — handle withPROJECTION_MATRIX[3][2]or fullINV_PROJECTION_MATRIXhomogeneous 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_COMPATIBILITYwhen reconstructingndc.z = depth * 2.0 - 1.0vsdepth! 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
PlaneMeshsubdivisions at96 × 96(~18k triangles) so vertex displacement stays under0.2 mson phones. depth_draw_never: Essential on transparent water usinghint_depth_textureso the water surface never reads its own depth in WebGL 2.
Verification Checklist
- Verify
#if CURRENT_RENDERER == RENDERER_COMPATIBILITYis present wheneverhint_depth_textureis linearized. - 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.
More Godot 4 techniques
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.
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.
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.
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.