# 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.

- **Canonical page:** https://gamecrew.ai/techniques/godot/stylized-water-foam
- **Techniques hub:** https://gamecrew.ai/techniques
- **Engine:** Godot 4
- **Category:** water
- **Tags:** `water`, `ocean`, `waves`, `gerstner`, `foam`, `depth`, `shader`, `gdshader`, `compatibility`, `shoreline`
- **Verification:** Compile-verified pattern

## 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 \in [-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

```glsl
#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`)

```glsl
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`)

```gdscript
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
