water-ripple

water-ripple — Impact Ripples on a Water Plane

Concentric expanding rings on a water surface, normal-distorted so the ripple actually refracts the reflection. The shader keeps a small ring buffer of (origin, time, amplitude) tuples and renders all of them simultaneously over a base water plane. GDScript exposes add_ripple(world_pos, amplitude) so any system (rain, footsteps, projectile impacts, fish) can spawn one with a single call.

When to use

• "Add ripples when the player walks through the puddle."
• "Rain hitting the lake should make ripples."
• "When the bullet hits the water, ripple."
• "Fish jumping leaves ripples."
• "Footsteps on the wet street should ripple."
• A water plane already exists and looks too static.

When NOT to use

• The user wants the whole water surface to wave (Gerstner / FFT ocean) — that's a separate ocean-water recipe; this is impact ripples on top.
• The user wants a 2D top-down ripple effect on a UI map — use canvas_item shader, not this spatial one.
• The user wants splash particles flying upward on impact — pair this with hit-spark (recolor blue) for the droplets; this only handles the ring on the surface.
• The user wants the ripple to physically displace floating objects — this is visual only. Use Area3D impulses for the simulation side.

Recipe

1. Files to create

addons/vfx/water-ripple/water_ripple.gdshader     # spatial shader on the water plane
addons/vfx/water-ripple/water_ripple_surface.gd    # MeshInstance3D controller w/ add_ripple()
addons/vfx/water-ripple/water_ripple.tscn          # reusable plane

2. Shader code

addons/vfx/water-ripple/water_ripple.gdshader:

shader_type spatial;
render_mode blend_mix, depth_draw_opaque, cull_disabled;

const int MAX_RIPPLES = 16;

uniform vec4  water_color    : source_color = vec4(0.10, 0.30, 0.45, 0.85);
uniform vec4  ripple_color   : source_color = vec4(0.85, 0.95, 1.00, 1.0);
uniform float water_metallic : hint_range(0.0, 1.0) = 0.4;
uniform float water_roughness: hint_range(0.0, 1.0) = 0.15;
uniform float fresnel_power  : hint_range(0.5, 8.0) = 4.0;
uniform float scroll_speed   : hint_range(0.0, 0.5) = 0.05;
uniform sampler2D normal_map : hint_normal;

// Per-ripple data: (origin.xz, start_time, amplitude * (1 if active else 0))
uniform vec4 ripples[MAX_RIPPLES];

// Ripple ages run off the controller's own clock, pushed here every frame. They
// cannot run off TIME: shader TIME wraps at
// rendering/limits/time/time_rollover_secs (3600 by default, verified), which
// would send every live ripple to a negative age once an hour of uptime.
uniform float now = 0.0;

uniform float ripple_speed       : hint_range(0.5, 8.0)  = 2.5;   // m/s expansion
uniform float ripple_wavelength  : hint_range(0.05, 1.0) = 0.20;  // distance between crests
uniform float ripple_lifetime    : hint_range(0.5, 6.0)  = 2.5;   // seconds visible
uniform float ripple_height      : hint_range(0.0, 0.4)  = 0.08;  // visual normal kick

void vertex() {
    // Sample ripples in vertex to displace Y for proper silhouette.
    vec3 wpos = (MODEL_MATRIX * vec4(VERTEX, 1.0)).xyz;
    float disp = 0.0;
    for (int i = 0; i < MAX_RIPPLES; i++) {
        vec4 r = ripples[i];
        if (r.w <= 0.0) continue;
        float age = now - r.z;
        if (age < 0.0 || age > ripple_lifetime) continue;
        float dist = length(wpos.xz - r.xy);
        float front = age * ripple_speed;
        float ring = exp(-pow((dist - front) / 0.25, 2.0));
        float fade = 1.0 - smoothstep(0.0, ripple_lifetime, age);
        disp += sin((dist - front) / ripple_wavelength * 6.2831) * ring * fade * r.w;
    }
    VERTEX.y += disp * ripple_height;
}

void fragment() {
    // Base water normal scroll.
    vec2 nuv = UV + vec2(TIME * scroll_speed, TIME * scroll_speed * 0.7);
    vec3 base_n = texture(normal_map, nuv).rgb * 2.0 - 1.0;

    // Composite ripple normals on top.
    vec3 wpos = (INV_VIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
    vec3 ripple_n = vec3(0.0, 0.0, 1.0);
    float ripple_glow = 0.0;
    for (int i = 0; i < MAX_RIPPLES; i++) {
        vec4 r = ripples[i];
        if (r.w <= 0.0) continue;
        float age = now - r.z;
        if (age < 0.0 || age > ripple_lifetime) continue;
        vec2 d = wpos.xz - r.xy;
        float dist = length(d);
        float front = age * ripple_speed;
        float ring = exp(-pow((dist - front) / 0.25, 2.0));
        float fade = 1.0 - smoothstep(0.0, ripple_lifetime, age);
        vec2 dir = (dist > 0.0001) ? (d / dist) : vec2(0.0);
        float wave = cos((dist - front) / ripple_wavelength * 6.2831);
        ripple_n.xy += dir * wave * ring * fade * r.w * 1.5;
        ripple_glow += ring * fade * r.w * 0.5;
    }

    // NORMAL_MAP is decoded by the engine (scene_forward_clustered.glsl:1427 —
    // `normal_map.xy = normal_map.xy * 2.0 - 1.0`), so hand it the RAW [0,1] texel
    // encoding. Assigning an already-decoded +/-1 vector makes a flat surface read
    // as permanent maximum tilt.
    NORMAL_MAP = normalize(base_n + vec3(ripple_n.xy, 0.0)) * 0.5 + 0.5;
    NORMAL_MAP_DEPTH = 0.6;

    // Fresnel-tinted color.
    float fres = pow(1.0 - clamp(dot(NORMAL, VIEW), 0.0, 1.0), fresnel_power);
    ALBEDO = mix(water_color.rgb, ripple_color.rgb, ripple_glow);
    METALLIC = water_metallic;
    ROUGHNESS = water_roughness;
    ALPHA = mix(water_color.a, 1.0, fres);
    EMISSION = ripple_color.rgb * ripple_glow * 0.4;
}