Skip to Content
defold-typescript libraries
selimanac

selimanac/defold-stylized-water-shader/water

A stylized water shader: animated wave surfaces, foam, sparkles, refraction and reflection, set through shader constants. A game object script calls init once with the camera, sun and water objects, then update(dt) and update_camera() every frame. The render script calls render_init(self) at the end of its init, after which self.predicates holds the water predicate, and render_update(self, state, self.predicates, draw_options_world) in its update (see water/render/water.render_script). The shader needs exclude_gles_sm100 = 1 under [shader] in game.project. Every setter writes a shader constant the next render_update uploads, and every getter returns the stored values as separate values.

  • GitHub: selimanac/defold-stylized-water-shader — pinned to bdcc1d8
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://github.com/selimanac/defold-stylized-water-shader/archive/bdcc1d863c64015fb70b117042f551795eb04211.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as water from "water.water"

Functions

init(camera_url: Url | string | Hash, camera_component_url: Url | string | Hash, sun_url: Url | string | Hash, water_url: Url | string | Hash, time_speed: number)

Stores the camera, sun and water objects and the time speed, then reads the camera position and near and far planes and the sun direction once. Call it from a game object script's init.

Parameters

  • camera_url: Url | string | Hash — The camera game object, whose world position the shader uses.
  • camera_component_url: Url | string | Hash — The camera component, whose near and far Z planes the shader uses.
  • sun_url: Url | string | Hash — The sun game object, whose position sets the light and the sun direction.
  • water_url: Url | string | Hash — The water surface game object, the origin of the sun direction.
  • time_speed: number — The multiplier update applies to dt to advance the wave time.

render_init(self: RenderScriptSelf)

Adds the water predicate to self.predicates, creates the scene render target at self.state.width by self.state.height with a color and a depth buffer, and creates the two constant buffers render_update draws with, all stored on self. Call it at the end of the render script's init, once self.predicates and self.state are set. Afterwards self.predicates types as Predicates, which render_update takes. From a defineRenderScript init, call it on the state init returns, which is merged onto self.

Parameters

  • self: RenderScriptSelf — The render script instance.

render_update(self: object, state: RenderState, predicates: Predicates, draw_options_world: render.DrawOptions)

Draws the model predicate into the scene render target, then draws model and the water to the default render target, sampling the scene's depth and color for edge foam and refraction. It needs render_init to have run on the same self, and raises otherwise. Call it from the render script's update after the world view and projection are set.

Parameters

  • self: object — The render script instance render_init ran on.
  • state: RenderState — The render state: the window size and the clear values.
  • predicates: Predicates — The render script's predicates; pass self.predicates, which holds the water predicate render_init added.
  • draw_options_world: render.DrawOptions — The draw options for the world, used for the scene pass.

update_sun()

Re-reads the sun position, which moves the light and recomputes the sun direction from the water object, replacing any direction set_sun_direction wrote.

update_camera()

Re-reads the camera world position and its near and far Z planes. Call it every frame.

update(dt: number)

Advances the wave time by dt times the time speed init stored, unless the timer is paused. Call it every frame.

Parameters

  • dt: number — The frame time in seconds.

pause(state: boolean)

Pauses or resumes the wave timer.

Parameters

  • state: boolean — true stops the timer, false resumes it.

set_wave1(direction: number, amplitude: number, wavelength: number, speed: number)

Sets the first wave layer.

Parameters

  • direction: number — The wave direction in radians, 0 to 2π: 0 east, π/2 north, π west, 3π/2 south.
  • amplitude: number — The wave height: 0.1 to 0.5 gentle, 0.5 to 1 medium, 1 to 2 rough, above 2 a storm.
  • wavelength: number — The distance between wave peaks: 10 to 20 choppy, 20 to 40 ocean waves, above 40 long gentle swells.
  • speed: number — The animation speed: 0.5 to 1 slow, 1 to 3 moderate, 3 to 5 fast, above 5 very fast.

get_wave1(): LuaMultiReturn<[ direction: number, amplitude: number, wavelength: number, speed: number ]>

Returns the first wave layer's direction, amplitude, wavelength and speed.

Returns

  • LuaMultiReturn<[ direction: number, amplitude: number, wavelength: number, speed: number ]>

set_wave2(direction: number, amplitude: number, wavelength: number, speed: number)

Sets the second wave layer, with the same ranges as set_wave1.

Parameters

  • direction: number — The wave direction in radians, 0 to 2π.
  • amplitude: number — The wave height: 0.1 to 0.5 gentle, 0.5 to 1 medium, 1 to 2 rough, above 2 a storm.
  • wavelength: number — The distance between wave peaks: 10 to 20 choppy, 20 to 40 ocean waves, above 40 long gentle swells.
  • speed: number — The animation speed: 0.5 to 1 slow, 1 to 3 moderate, 3 to 5 fast, above 5 very fast.

get_wave2(): LuaMultiReturn<[ direction: number, amplitude: number, wavelength: number, speed: number ]>

Returns the second wave layer's direction, amplitude, wavelength and speed.

Returns

  • LuaMultiReturn<[ direction: number, amplitude: number, wavelength: number, speed: number ]>

set_wave_normal_params(scale: number, speed: number)

Sets the animated normal map that adds ripple detail to the surface.

Parameters

  • scale: number — The normal map tiling: 5 large ripples, 10 medium, 20 tiny.
  • speed: number — The animation speed: 0.5 slow, 1 normal, 2 fast.

get_wave_normal_params(): LuaMultiReturn<[ scale: number, speed: number ]>

Returns the normal map tiling and animation speed.

Returns

  • LuaMultiReturn<[ scale: number, speed: number ]>

set_shallow_color(r: number, g: number, b: number)

Sets the water color in shallow areas. The shader always uses an alpha of 1.

Parameters

  • r: number — The red component, 0 to 1.
  • g: number — The green component, 0 to 1.
  • b: number — The blue component, 0 to 1.

get_shallow_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>

Returns the shallow water color's red, green and blue components.

Returns

  • LuaMultiReturn<[ r: number, g: number, b: number ]>

set_deep_color(r: number, g: number, b: number)

Sets the water color in deep areas.

Parameters

  • r: number — The red component, 0 to 1.
  • g: number — The green component, 0 to 1.
  • b: number — The blue component, 0 to 1.

get_deep_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>

Returns the deep water color's red, green and blue components.

Returns

  • LuaMultiReturn<[ r: number, g: number, b: number ]>

set_far_color(r: number, g: number, b: number)

Sets the water color far from the camera, which the surface fades to with distance.

Parameters

  • r: number — The red component, 0 to 1.
  • g: number — The green component, 0 to 1.
  • b: number — The blue component, 0 to 1.

get_far_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>

Returns the far water color's red, green and blue components.

Returns

  • LuaMultiReturn<[ r: number, g: number, b: number ]>

set_foam_params(scale: number, speed: number, noise_scale: number, contribution: number)

Sets the foam's look and animation.

Parameters

  • scale: number — The foam texture tiling; lower values give bigger foam patches.
  • speed: number — The animation speed.
  • noise_scale: number — The normal map distortion: 0 none, 0.5 moderate, 1 heavy.
  • contribution: number — The overall foam visibility: 0 no foam, 0.5 subtle, 1 full.

get_foam_params(): LuaMultiReturn<[ scale: number, speed: number, noise_scale: number, contribution: number ]>

Returns the foam tiling, speed, normal map distortion and visibility.

Returns

  • LuaMultiReturn<[ scale: number, speed: number, noise_scale: number, contribution: number ]>

set_density_params(distance_density: number, depth_density: number)

Sets how the color fades with distance and blends with depth.

Parameters

  • distance_density: number — How quickly the color fades to the far color: 0.01 very slow, 0.1 normal, 0.5 quick.
  • depth_density: number — How quickly the color moves from the shallow color to the deep color with water depth.

get_density_params(): LuaMultiReturn<[ distance_density: number, depth_density: number ]>

Returns the distance fade rate and the depth blending intensity.

Returns

  • LuaMultiReturn<[ distance_density: number, depth_density: number ]>

set_sun_params(exponent: number)

Sets the sharpness of the sun's specular highlight.

Parameters

  • exponent: number — The highlight sharpness: 100 big and soft, 1000 medium, 10000 tiny and sharp.

get_sun_params(): number

Returns the sun highlight sharpness.

Returns

  • number

set_sun_color(r: number, g: number, b: number)

Sets the sun light color.

Parameters

  • r: number — The red component, 0 to 1.
  • g: number — The green component, 0 to 1.
  • b: number — The blue component, 0 to 1.

get_sun_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>

Returns the sun color's red, green and blue components.

Returns

  • LuaMultiReturn<[ r: number, g: number, b: number ]>

set_sun_direction(x: number, y: number, z: number)

Sets the directional light direction. init and update_sun overwrite it with the direction from the water object to the sun.

Parameters

  • x: number — The X component of the normalized direction.
  • y: number — The Y component of the normalized direction.
  • z: number — The Z component of the normalized direction.

get_sun_direction(): LuaMultiReturn<[ x: number, y: number, z: number ]>

Returns the X, Y and Z components of the sun direction.

Returns

  • LuaMultiReturn<[ x: number, y: number, z: number ]>

set_sparkle_params(scale: number, speed: number, exponent: number, enabled?: number)

Sets the sparkle (glitter) effect.

Parameters

  • scale: number — The sparkle texture tiling.
  • speed: number — The animation speed.
  • exponent: number — The sharpness: 1000 many soft sparkles, 10000 medium, 100000 very few, very sharp ones.
  • enabled?: number — 0 disables sparkles and 1 enables them. When omitted, the current value is kept.

get_sparkle_params(): LuaMultiReturn<[ scale: number, speed: number, exponent: number, enabled: number ]>

Returns the sparkle tiling, speed and sharpness, and 1 when sparkles are enabled or 0 when not.

Returns

  • LuaMultiReturn<[ scale: number, speed: number, exponent: number, enabled: number ]>

enable_sparkle()

Enables the sparkle effect.

disable_sparkle()

Disables the sparkle effect, which saves eight texture samples per fragment.

is_sparkle_enabled(): boolean

Returns true when the sparkle effect is enabled.

Returns

  • boolean

set_sparkle_color(r: number, g: number, b: number)

Sets the sparkle tint color.

Parameters

  • r: number — The red component, 0 to 1.
  • g: number — The green component, 0 to 1.
  • b: number — The blue component, 0 to 1.

get_sparkle_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>

Returns the sparkle color's red, green and blue components.

Returns

  • LuaMultiReturn<[ r: number, g: number, b: number ]>

set_edge_foam_params(depth_scale: number, noise_strength: number, edge_softness: number, alpha: number)

Sets the foam drawn where the water meets other geometry, based on water depth.

Parameters

  • depth_scale: number — How quickly the foam fades with depth; lower values give more foam.
  • noise_strength: number — The noise distortion strength, about 0.2 to 0.5.
  • edge_softness: number — The edge blend softness, about 0.02 to 0.15.
  • alpha: number — The overall foam opacity, 0 to 1.

get_edge_foam_params(): LuaMultiReturn<[ depth_scale: number, noise_strength: number, edge_softness: number, alpha: number ]>

Returns the edge foam depth scale, noise strength, edge softness and opacity.

Returns

  • LuaMultiReturn<[ depth_scale: number, noise_strength: number, edge_softness: number, alpha: number ]>

set_edge_foam_type(type: 0 | 1)

Sets how the edge foam is drawn. It also prints SET and the type on every call.

Parameters

  • type: 0 | 1 — 0 draws a solid color, 1 a texture.

get_edge_foam_type(): number

Returns the edge foam type: 0 for a solid color, 1 for a texture.

Returns

  • number

set_edge_foam_color(r: number, g: number, b: number)

Sets the edge foam color.

Parameters

  • r: number — The red component, 0 to 1.
  • g: number — The green component, 0 to 1.
  • b: number — The blue component, 0 to 1.

get_edge_foam_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>

Returns the edge foam color's red, green and blue components.

Returns

  • LuaMultiReturn<[ r: number, g: number, b: number ]>

set_refraction_params(strength: number, chromatic_aberration?: number)

Sets the screen-space refraction.

Parameters

  • strength: number — The refraction intensity: 0 off, 0.5 moderate, 1 strong.
  • chromatic_aberration?: number — The color separation: 0 off, 0.5 subtle, 1 strong. Defaults to 0.

get_refraction_params(): LuaMultiReturn<[ strength: number, chromatic_aberration: number ]>

Returns the refraction strength and chromatic aberration.

Returns

  • LuaMultiReturn<[ strength: number, chromatic_aberration: number ]>

set_reflection_params(strength: number, fresnel_power?: number)

Sets the cubemap reflection. The reflection samples the cubemap bound to the water material's reflection_cubemap sampler; this module binds none.

Parameters

  • strength: number — The reflection intensity: 0 off, 0.5 moderate, 1 strong.
  • fresnel_power?: number — How much stronger the reflection is at grazing angles, 1 to 5: 1 the same at every angle, 3 natural, 5 very strong. Defaults to 3.

get_reflection_params(): LuaMultiReturn<[ strength: number, fresnel_power: number ]>

Returns the reflection strength and fresnel power.

Returns

  • LuaMultiReturn<[ strength: number, fresnel_power: number ]>

set_skybox_cubemap(cubemap_path: string)

  • Deprecated — Upstream does not implement cubemap reflections: a cubemap path cannot be passed to render.enable_texture.

Prints a warning and does nothing else.

Parameters

  • cubemap_path: string — The cubemap texture path, for example /main/skybox.cubemap.

get_skybox_cubemap(): undefined

  • Deprecated — Upstream does not implement cubemap reflections: a cubemap path cannot be passed to render.enable_texture.

Returns undefined.

Returns

  • undefined

set_lod_params(sparkle_distance: number, foam_distance: number)

Sets the level-of-detail distances beyond which effects are simplified.

Parameters

  • sparkle_distance: number — The distance beyond which sparkles are skipped, saving eight texture samples, 0 to 500. The default is 100.
  • foam_distance: number — The distance beyond which a simplified foam is drawn, saving three texture samples, 0 to 500. The default is 150.

get_lod_params(): LuaMultiReturn<[ sparkle_distance: number, foam_distance: number ]>

Returns the sparkle and foam level-of-detail distances.

Returns

  • LuaMultiReturn<[ sparkle_distance: number, foam_distance: number ]>

Types

RenderScriptSelf

RenderScriptSelf.predicates: { model: render.RenderPredicate; }

The render script's predicates, which hold model. render_init adds water.

RenderScriptSelf.state: { width: number; height: number; }

The render state, whose size render_init creates the scene render target at.

Predicates

Predicates.model: render.RenderPredicate

The model predicate, drawn into the scene render target and then to the screen.

Predicates.water: render.RenderPredicate

The water predicate render_init adds to the render script's self.predicates.

RenderState

RenderState.window_width: number

The window width in pixels, which the scene render target is resized to.

RenderState.window_height: number

The window height in pixels, which the scene render target is resized to.

RenderState.clear_buffers: LuaMap<render.ClearBufferKey, number | Vector4>

The clear values render.clear receives for the scene render target.

On this page

Functionsinit(camera_url: Url | string | Hash, camera_component_url: Url | string | Hash, sun_url: Url | string | Hash, water_url: Url | string | Hash, time_speed: number)render_init(self: RenderScriptSelf)render_update(self: object, state: RenderState, predicates: Predicates, draw_options_world: render.DrawOptions)update_sun()update_camera()update(dt: number)pause(state: boolean)set_wave1(direction: number, amplitude: number, wavelength: number, speed: number)get_wave1(): LuaMultiReturn<[ direction: number, amplitude: number, wavelength: number, speed: number ]>set_wave2(direction: number, amplitude: number, wavelength: number, speed: number)get_wave2(): LuaMultiReturn<[ direction: number, amplitude: number, wavelength: number, speed: number ]>set_wave_normal_params(scale: number, speed: number)get_wave_normal_params(): LuaMultiReturn<[ scale: number, speed: number ]>set_shallow_color(r: number, g: number, b: number)get_shallow_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>set_deep_color(r: number, g: number, b: number)get_deep_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>set_far_color(r: number, g: number, b: number)get_far_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>set_foam_params(scale: number, speed: number, noise_scale: number, contribution: number)get_foam_params(): LuaMultiReturn<[ scale: number, speed: number, noise_scale: number, contribution: number ]>set_density_params(distance_density: number, depth_density: number)get_density_params(): LuaMultiReturn<[ distance_density: number, depth_density: number ]>set_sun_params(exponent: number)get_sun_params(): numberset_sun_color(r: number, g: number, b: number)get_sun_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>set_sun_direction(x: number, y: number, z: number)get_sun_direction(): LuaMultiReturn<[ x: number, y: number, z: number ]>set_sparkle_params(scale: number, speed: number, exponent: number, enabled?: number)get_sparkle_params(): LuaMultiReturn<[ scale: number, speed: number, exponent: number, enabled: number ]>enable_sparkle()disable_sparkle()is_sparkle_enabled(): booleanset_sparkle_color(r: number, g: number, b: number)get_sparkle_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>set_edge_foam_params(depth_scale: number, noise_strength: number, edge_softness: number, alpha: number)get_edge_foam_params(): LuaMultiReturn<[ depth_scale: number, noise_strength: number, edge_softness: number, alpha: number ]>set_edge_foam_type(type: 0 | 1)get_edge_foam_type(): numberset_edge_foam_color(r: number, g: number, b: number)get_edge_foam_color(): LuaMultiReturn<[ r: number, g: number, b: number ]>set_refraction_params(strength: number, chromatic_aberration?: number)get_refraction_params(): LuaMultiReturn<[ strength: number, chromatic_aberration: number ]>set_reflection_params(strength: number, fresnel_power?: number)get_reflection_params(): LuaMultiReturn<[ strength: number, fresnel_power: number ]>set_skybox_cubemap(cubemap_path: string)get_skybox_cubemap(): undefinedset_lod_params(sparkle_distance: number, foam_distance: number)get_lod_params(): LuaMultiReturn<[ sparkle_distance: number, foam_distance: number ]>TypesRenderScriptSelfRenderScriptSelf.predicates: { model: render.RenderPredicate; }RenderScriptSelf.state: { width: number; height: number; }PredicatesPredicates.model: render.RenderPredicatePredicates.water: render.RenderPredicateRenderStateRenderState.window_width: numberRenderState.window_height: numberRenderState.clear_buffers: LuaMap<render.ClearBufferKey, number | Vector4>