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- 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— togame.projectunder[project]dependencies, then Fetch Libraries in the Defold editor. - Run
bunx @defold-typescript/cli resolveto materialize its types. - Import it under a namespace alias of your choice:
import * as water from "water.water"
- This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit,
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)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 ]>
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 multiplierupdateapplies todtto 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 instancerender_initran on.state:RenderState— The render state: the window size and the clear values.predicates:Predicates— The render script's predicates; passself.predicates, which holds thewaterpredicaterender_initadded.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—truestops the timer,falseresumes it.
set_wave1(direction: number, amplitude: number, wavelength: number, speed: number)
Sets the first wave layer.
Parameters
direction:number— The wave direction in radians,0to2π:0east,π/2north,πwest,3π/2south.amplitude:number— The wave height:0.1to0.5gentle,0.5to1medium,1to2rough, above2a storm.wavelength:number— The distance between wave peaks:10to20choppy,20to40ocean waves, above40long gentle swells.speed:number— The animation speed:0.5to1slow,1to3moderate,3to5fast, above5very 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,0to2π.amplitude:number— The wave height:0.1to0.5gentle,0.5to1medium,1to2rough, above2a storm.wavelength:number— The distance between wave peaks:10to20choppy,20to40ocean waves, above40long gentle swells.speed:number— The animation speed:0.5to1slow,1to3moderate,3to5fast, above5very 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:5large ripples,10medium,20tiny.speed:number— The animation speed:0.5slow,1normal,2fast.
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,0to1.g:number— The green component,0to1.b:number— The blue component,0to1.
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,0to1.g:number— The green component,0to1.b:number— The blue component,0to1.
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,0to1.g:number— The green component,0to1.b:number— The blue component,0to1.
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:0none,0.5moderate,1heavy.contribution:number— The overall foam visibility:0no foam,0.5subtle,1full.
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.01very slow,0.1normal,0.5quick.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:100big and soft,1000medium,10000tiny 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,0to1.g:number— The green component,0to1.b:number— The blue component,0to1.
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:1000many soft sparkles,10000medium,100000very few, very sharp ones.enabled?:number—0disables sparkles and1enables 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,0to1.g:number— The green component,0to1.b:number— The blue component,0to1.
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, about0.2to0.5.edge_softness:number— The edge blend softness, about0.02to0.15.alpha:number— The overall foam opacity,0to1.
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—0draws a solid color,1a 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,0to1.g:number— The green component,0to1.b:number— The blue component,0to1.
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:0off,0.5moderate,1strong.chromatic_aberration?:number— The color separation:0off,0.5subtle,1strong. Defaults to0.
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:0off,0.5moderate,1strong.fresnel_power?:number— How much stronger the reflection is at grazing angles,1to5:1the same at every angle,3natural,5very strong. Defaults to3.
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,0to500. The default is100.foam_distance:number— The distance beyond which a simplified foam is drawn, saving three texture samples,0to500. The default is150.
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.