Water

Split

It has been suggested that this article or section be split into multiple articles: Water (shader) and Liquid materials.
The latter should document the shader-agnostic parameters for %CompileWater and %CompileSlime materials. (Discuss)

Water is a Pixel shader available in all Source games.

Water reflecting entities in real-time in Episode Two.

Left 4 Dead 2 introduced flowing water and lightmapped fog.

It creates water that realistically reflects and refracts the world, and that can flow throughout a map.

Tip: Water does not need to use the Water shader! If a less realistic effect is desired, or the water volume is oddly shaped, other shaders can be used, such as LightmappedGeneric or Refract. The method for creating the materials is the same.

Todo: Move shader-agnostic water parameters to a separate section.

Special behavior

Expensive and cheap: Water materials fall into two groups: expensive and cheap. Expensive water reflects and refracts the world in real-time by generating a planar reflection map, which was rendered three times, while cheap water uses an $envmap and does not refract. In games prior to Left 4 Dead engine branch, users can disable expensive water rendering through their video options, so always place env_cubemap entities throughout a map.; On the video options, Source provides three water reflection options: Simple reflections (uses cubemap water), Reflect world (reflects world geometry only) and Reflect all (reflects world and entities/props)
Above and below: Water actually requires two materials: one for above the surface and one for below. These materials are independent of each other, but for proper effect need to correlate in most areas.
Flow Mapping: Water can flow in arbitrary directions. It's very tricky to create a flow map by hand however, and the tool Valve used internally hasn't been released.

Shader parameters

Textures

$basetexture <texture> (in all games since ): Usually referred to as a "sludge-layer", acts as a layer on top of the surface of the $AboveWater Material.
Warning: The $BaseTexture will only be lightmapped if there is no $FlowMap!

Warning: When not using a $FlowMap, this parameter does not work with projected textures or $LightMapWaterFog!

Note: In games before , the surface is a combination of fog color, animated bump map, reflection and refraction.

$abovewater <boolean>: Whether this material is used for above or below the water’s surface.

Note: Not setting this in the VMT will automatically force it to 1. If not defined, a warning will appear saying Need to set $abovewater for material x

$bottommaterial <material>: Required parameter. This is the material (not texture) to use when underneath the water’s surface. The bottom material must have $reflecttexture, $abovewater and $envmap disabled, but can otherwise do whatever it wants.
Tip: Add %notooltexture to the bottom material to hide it in the texture browser (not in ).

Note: If the above water material does not have reflections, refractions, or $underwateroverlay: $abovewater can be omitted, $nocull can be used, and $bottommaterial can be set to the same material as the abovewater material.

$underwateroverlay <material> (in all games since ): Applies a refracting screen overlay when the camera is underwater. Generally used with effects\water_warp01. Requires $abovewater to be 0.

Note: This is technically not a parameter on the water shader, meaning it can be abused for other unintended purposes! The overlay may still be applied even when the underwater material is told not to render ( $no_draw)

$bumpmap <texture> (DX8): This material shader parameter is described on its own page.

$normalmap <texture>

A Du/dv map for DirectX 8 rendering ($bumpmap), and a bump map for DirectX 9 and above ($normalmap). These should be animated unless the water is to be perfectly still or you're using a flow map, which makes an animated bump map redundant.

Note: The $normalmap parameter is unique to the Water shader, and uses a normal map. A du/dv map is used for $bumpmap when using the Water shader. The $dudvmap command is obsolete.

Tip: Use $bumptransform with the TextureScroll proxy to move the normal map in pre-2006 engine branches.

$dudvframe <integer>

$bumpframe <integer>: Frame to start the animated du/dv map and bump map on, respectively. Somewhat confusingly, $bumpframe affects $normalmap, which should be pointing to a bump map.

$bumptransform <matrix>

Transforms the bump map texture. The default position is center .5 .5 scale 1 1 rotate 0 translate 0 0.

center defines the point of rotation. Only useful if rotate is being used.
scale fits the texture into the material the given number of times. 2 1 is a 50% scale in the horizontal X axis while the vertical Y axis is still at original scale.
rotate rotates the texture counter-clockwise in degrees. Accepts any number, including negatives.
translate shifts the texture by the given numbers. .5 will shift it half-way. 1 will shift it once completely over, which is the same as not moving it at all.

Note: All values must be included!

Bug:Scaling the texture may cause odd issues where the Texture Lock tool in Hammer will not actually lock the texture in place. [todo tested in ?]

Bug:Rotating textures applied on brushes will rotate around the map origin (confirm: Orangebox engine only?). A fix for this is to change the center position in the VMT to the brush's origin. [todo tested in ?]

$scale <vector2>: Unused Parameter.-Likely a precursor of $RefractAmount and $ReflectAmount.
In and 's Shadercode it will bundle up $Reflect/$RefractAmount into a single float4 to save some instructions, like so:
"[$ReflectAmount, $ReflectAmount, $RefractAmount, $RefractAmount]" This is pretty much $Scale but with two more components.
The constant register is referred to as 'g_ReflectRefractScale' as well. The only thing the shader does with it now is set a default value of "[1 1]".

$flashlighttint <float> (in all games since ): Tints the results of projected textures on the water. The flashlight mainly affects the brightness of the fog in the water. A comment in 's Shadercode explains :
"The flashlight on the water surface is basically the diffuse flashlight * waterfogcolor * g_flFlashlightTint. g_flFlashlightTint is tweakable in cases where the water fog color is really dark and the flashlight doesn't show up, etc."

$waterdepth <float> (in all games since ): Todo: What does this do exactly? Seems like it's related to $waterblendfactor, Found in liquids/nuke_water.vmt. Found in 2006/2007 code, does it do anything there?

$depth_feather <integer> (in all games since ): Todo: What does this do exactly? Found in liquids/nuke_water.vmt.

Fog

$fogenable <boolean>: Enable volumetric fog for the water. If disabled on the Water shader, fog will be applied to the brush uniformly.

Note: This parameter does not exist on the shader itself, the logic behind it is handled somewhere else.

$fogcolor <RGB matrix>: Color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.

Important: If this parameter is not defined in a VMT, the shader will force its value to "[1 0 0]" and spew an error message saying Material x needs to have a $fogcolor.

Warning:
Cheap water treats this parameters as a linear value where 0.0 is 0% and 1.0 is 100%.
Expensive water treats this parameter as a Gamma value,
and due do this, each component ( red, green and blue respectively ) can not go above 1.0 or below 0.0 ( on expensive water )

To calculate the eventual linear value that the shader is supplied with, apply the formula x^(1/2.2)
Tip: While expensive water cannot, cheap water can go higher than 1.0, achieving a more "neon" effect.

$fogstart <float>

Distance in units/inches from the eye at which water fog starts.

Warning: Must be 0 for edge fading to work properly.

$fogend <float>: Distance in units/inches from the eye at which water fog ends.

$lightmapwaterfog <boolean> (in all games since ): Allows the fog to receive lightmaps, so that static objects can cast shadows onto the water. This must be enabled when the map is compiled.

Note: Bumped Lightmaps are only enabled when a $BaseTexture has been defined, without it, a regular Lightmap will be used instead.

Warning: This feature does not exist for cheap water.

Reflection

$reflecttexture <texture>: Texture to use for reflection. For real-time reflections, use _rt_WaterReflection.

$reflectamount <float>: Amount of warp for the reflection. Higher values produce more visible reflections.

$reflecttint <RGB matrix>: Color tint for both expensive and cheap reflections.

Warning:
This parameter is in Gamma space on expensive water, meaning it will be converted to linear before being sent to the shader.

To calculate the eventual linear value that the shader is supplied with, apply the formula x^(1/2.2)

$envmap <env_cubemap/texture>

See $envmap. Provides reflections for cheap water.

Note: Don't use this on underwater materials^[Why?].

$envmapframe <integer>: The frame to start an animated cubemap on.

$forceenvmap <boolean> (in all games since ): Forces the water to use $envmap for reflections.

$forcecheap <boolean>: Force the water to render itself as cheap, regardless of the map's water_lod_control entity settings or the Water detail video settings. This will disable real-time reflection and instead use $envmap. Refraction is assumed to be opaquely the water fog color.

$forceexpensive <boolean>: Force the water to render itself as expensive, regardless of the map's water_lod_control entity settings or the Water detail video settings.

$cheapwaterstartdistance <float>: Distance from the eye in inches that the shader should start transitioning to a cheaper water shader.

$cheapwaterenddistance <float>: Distance from the eye in inches that the shader should finish transitioning to a cheaper water shader.

$reflectentities <boolean>: Force the water to reflect entities, regardless of the Water detail video settings. By default this was disabled, meaning no entities are reflected unless user chose "Reflect all" water detail settings.

$reflectonlymarkedentities <boolean> (in all games since ): Make the water reflect only entities and static props with "Render in Fast Reflections" enabled.

$reflectskyboxonly <boolean> (in all games since ): Make the water reflect only the skybox.
Bug:Not using this setting in causes the env_sun sprite to appear through the floor whenever water without "reflectskyboxonly" is on screen. [todo tested in ?]

$reflect2dskybox <boolean> (in all games since ): Make the water reflect the skybox material in addition to other reflections.

$reflect3dskybox <boolean> (only in )

Make the water reflect the 3D skybox in addition to other reflections. Added in the Danger Zone update and used on dz_blacksite.

Note: Requires a sky_camera entity to be placed in the map, otherwise this might cause crashes.

$reflectblendfactor <float>: Todo: What does this do?

$nofresnel <boolean> (in all games since )

Disable the fresnel on the water's reflection.

Bug:Does not do anything in any engine branch. [todo tested in ?]

$forcefresnel <float> (in all games since ): Force this amount of fresnel on the water. Higher values usually cause the water to appear brighter.
Bug:Does not work properly in . [todo tested in ?]

$basereflectance <float>: Todo: What is this?

$maxreflectance <float>: Todo: What is this?

Refraction

$refract <boolean> (in all games since ): Whether the material should refract at all.

$refracttexture <texture>

Texture to use for refraction. For real-time refractions, use _rt_WaterRefraction.

Tip: Specify $refracttexture without $reflecttexture to get real-time refraction on $envmap reflections.

$refractamount <float>: Amount of warp for the refraction. Higher values produce more warping.

$refracttint <RGB matrix>: Color of the refraction.

Warning: It is recommended that you set this to white or something close to white so that edge transitions work properly on DX9.

Warning: This parameter is in Gamma space, meaning it will be converted to linear before being sent to the shader.
To calculate the eventual linear value that the shader is supplied with, apply the formula x^(1/2.2)

$blurrefract <boolean> (DX9 SM2) (in all games since )

Blurs the refraction when underwater.

Warning: Underwater materials only; this will cause buggy behavior on any material with $abovewater set to 1.

$pseudotranslucent <boolean> (in all games since ): Make the water translucent. This is a cheap substitute for refractive water; do not use this when refraction is enabled.

$waterblendfactor <normal> (in all games since ): How translucent the water should be when $pseudotranslucent is enabled. At 0, the water is completely transparent, while at 1 the water is completely opaque.

Flowing water

$scroll1 "[<normal X> <normal Y>]" (in all games since )
$scroll2 "[<normal X> <normal Y>]" (in all games since ): If $scroll1 is defined and X is not zero, two more instances of the normal map will be drawn in such a way that they are merged together. The first layer is 7x larger and rotated 45°; the second is 2x larger and rotated 90°. The parameters specify the speed and direction that the extra layers will move. (Valve's materials usually contain a third number, but it doesn't have any apparent effect and is most likely obsolete.)

Flow maps

$flowmap <texture> (in all games since ) (also in )

Texture that defines flow velocity by skewing and scrolling the $normalmap. Valve generates their flowmaps with Houdini.

Video of the effect. For technical details, see Alex Vlachos' SIGGRAPH 2010 paper and Valve's GDC 2011 paper.

Warning: Using this parameter with $BaseTexture will make the $BaseTexture not be affected by lighting.

A flow map texture.
The flow map texture in-engine, shown with $flow_debug 1.
The result in-engine.

$flow_normaluvscale <float> (in all games since ) (also in ): The number of world units covered by the normal map before it repeats. Typically in the 100s.

$flow_worlduvscale <float> (in all games since ) (also in ): The number of times the flow map fits into the material. Face texture scale affects this.

$flow_uvscrolldistance <float> (in all games since ) (also in ): How far along the flow map the normal map should be distorted. Higher values lead to more distortion.

$flow_timeintervalinseconds <float> (in all games since ) (also in ): Time needed for the normal map to cross the $flow_uvscrolldistance.

$flow_timescale <float> (in all games since ): Modifies flow speed without affecting the amount of distortion.

$flow_bumpstrength <normal> (in all games since ) (also in ): How rough the surface of the water is.

$flow_noise_texture <texture> (in all games since ) (also in ): A treatment texture used to break up repetition of the normal map.

$flow_noise_scale <float> (in all games since ) (also in ): How many times to fit the noise texture into the normal map. Typically around 0.01.

$flow_debug <boolean> (in all games since ) (also in ): Replaces the water surface with a literal rendering of the flow map.
Bug:Although the flow map will show up in Hammer, it may not be in the correct place! Don't rely on Hammer's view for alignment. [todo tested in ?]

Todo: Add

Black Mesa parameters.

Basetexture Flow

$basetexture <texture> (in all games since ) (also in )

A "sludge layer", used in

for the sludge and debris in test chambers. The alpha channel of the $basetexture acts as a mask for the reflection; darker values are more reflective, while lighter values are less reflective.

Note: From

onwards, the opacity of the $basetexture is controlled by the alpha channel of the flow map.

$color_flow_uvscale <float> (in all games since ) (also in ): The number of world units covered by the base texture before it repeats. Typically in the 100s.

$color_flow_timescale <float> (in all games since ): Modifies flow speed without affecting the amount of distortion.

$color_flow_timeintervalinseconds <float> (in all games since ) (also in ): Time needed for the base texture to cross the $color_flow_uvscrolldistance.

$color_flow_uvscrolldistance <float> (in all games since ) (also in ): How far along the flow map the base texture should be distorted. Higher values lead to more distortion.

$color_flow_lerpexp <float> (in all games since ) (also in )

How sharp the transition should be between repeats, should be 1.

Todo: Better explanation

$color_flow_displacebynormalstrength <float> (in all games since ) (also in ): How much the normal map affects the base texture. Uses extremely low values, usually 0.01 or less.

Authoring a flow map

Directions of water flow depend on the red and green channels of the flow map.

Overall, trying to create a flow map manually is a nightmare. Painting the flow map, fitting it into the world, and painting foam, is extremely difficult.

But if you do want to give it a try, flow direction is read from the red and green channels of the flow map. 50% tone means no movement.

The texture scale of any faces using a water texture with a flow map appear to have a direct correlation on the flow map. The fewer water faces or planes you use the easier the process of authoring a custom flow map will be (selecting all of your water faces and using 'treat as one' when using the fit scaling may also be an option)

Red channel: X axis
Green channel: Y axis
Alpha channel: Controls $basetexture blending from onwards.

There are now tools to assist in painting flowmaps.: Flow field editor from algoholic.eu : http://algoholic.eu/another-flow-field-editor-update/ ^{[dead link]}; Flowmap generator (paid): http://www.superpositiongames.com/products/flowmap-generator; Creating flowmaps using Houdini (UDK) : https://www.dropbox.com/s/ii2x077vj64lyhl/Water%20Flow%20For%20UDK.pdf ^{[dead link]}

Other

%CompileWater <boolean>: This is needed to make a map using the material compile properly.

%CompileSlime <boolean>: Can be used instead of %CompileWater to get different particles.
Important: Planar reflections doesn't work with this.

$surfaceprop <water>: Tells the physics system that the surface is water. See $surfaceprop.

%tooltexture <texture>: Defines the texture Hammer will display in the material browser. Any texture can be used, but it is customary to use the $normalmap.

WaterLOD proxy: This connects the water_lod_control entity in a level to the water’s internal parameters. This must be declared in the material for the LOD mechanisms to work properly.

Water

Contents

Special behavior