Water (shader)
Water
is a material shader used for water. Water in Source is complex, and can be animated, refract and reflect the world in real-time, and flow throughout a map.
Contents
Special behaviour
- Expensive and cheap
Water
materials fall into two groups: expensive and cheap. Expensive water reflects and refracts the world in real-time, while cheap water uses an$envmap
and does not refract. Users can disable expensive water rendering through their video options, so always place env_cubemaps.- 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 of course 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
. The surface is a combination of fog color, animated bump map, reflection and refraction.$abovewater <bool>
- Whether this material is used for above or below the water’s surface.
$bottommaterial <material>
- Required field. 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. $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. $bumpmap <texture>
$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 flowmap, which makes an animated bump map redundant. Note: The
$normalmap
command is unique to theWater
shader, and uses a normal map. A du/dv map is used for$bumpmap
when using theWater
shader. The$dudvmap
command is obsolete.Tip: Use
$bumptransform
with the TextureScroll proxy to move the normal map in pre-2006 engine branches.$dudvframe <int>
$bumpframe <int>
- 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 ifrotate
is being used.scale
fits the texture into the material the given number of times. '2 1
' is a 50% scale in the X axis.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.
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.
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.
$scale <vector2>
- To do: What does this do?
$flashlighttint <float>
(in all games since)
Confirm:How much projected textures should tint the water?
$waterdepth <float>
(in all games since)
- To do: 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 <int>
(in all games since)
- To do: What does this do exactly? Found in liquids/nuke_water.vmt.
Fog
$fogcolor <RGB matrix>
- Color of the water’s volumetric fog. Generally this value should match the color used in the bottom material.
$fogenable <bool>
- Enable volumetric fog for the water.
$fogstart <float>
- Distance in inches from the eye at which water fog starts.
Warning: Must be 0 for edge fading to work properly.
$fogend <float>
- Distance in inches from the eye at which water fog ends.
$lightmapwaterfog <bool>
(in all games since)
- Allows the fog to receive lightmaps, so that static objects can cast shadows onto the water. Must be enabled when the map is compiled.
Reflection
$reflecttexture <texture>
- Texture to use for reflection. For real-time reflections, use
_rt_WaterReflection
. $envmap <env_cubemap / texture>
- See
$envmap
. Provides reflections for cheap water. Note: Don't use this on underwater materials.
$envmapframe <int>
- The frame to start an animated cubemap on.
$forceenvmap <bool>
(in all games since)
- Forces the water to use
$envmap
for reflections. $forcecheap <bool>
- Force the water to render itself as cheap, regardless of the map's
water_lod_control
entity settings or the user's settings. This will disable real-time reflection and instead use$envmap
. Refraction is assumed to be opaquely the water fog color. $forceexpensive <bool>
- Force the water to render itself as expensive, regardless of the map's
water_lod_control
entity settings or the user's 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.
$reflect2dskybox
<bool> (in all games since)
- Make the water reflect the skybox material in addition to other reflections.
$reflect3dskybox
<bool> (in all games since)
- 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.$reflectskyboxonly <bool>
(in all games since)
- Make the water reflect only the skybox.
$reflectentities <bool>
- Make the water reflect entities. By default, no entities are reflected.
$reflectonlymarkedentities <bool>
(in all games since)
- Make the water reflect only entities and static props with "Render in Fast Reflections" enabled.
$reflectamount <float>
- Amount of warp for the reflection. Higher values produce more visible reflections.
$reflecttint <RGB matrix>
- Color tint for the real-time reflection and environment map.
$reflectblendfactor <float>
- To do: What does this do?
$nofresnel <bool>
(in all games since)
- Disable the fresnel on the water's reflection.
Bug: Does not do anything in any engine branch.
$forcefresnel <float>
(in all games since)
- Force this amount of fresnel on the water. Higher values usually cause the water to appear brighter.
$basereflectance <float>
- To do: What is this?
$maxreflectance <float>
- To do: What is this?
Refraction
$refract <bool>
(in all games since)
- Whether the material should refract at all.
$refractamount <float>
- Amount of warp for the refraction. Higher values produce more warping.
$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.$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.
$blurrefract <bool>
(in all games since) (DX9+)
- Applies a blur to the refraction when underwater.
Warning: Underwater materials only; this will cause buggy behavior on any material with
$abovewater
set to 1.$pseudotranslucent <bool>
(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.)
Flowmaps
$flowmap <texture>
(in all games since)
- 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.
$flow_normaluvscale <float>
(in all games since)
- The number of world units covered by the normal map before it repeats. Typically in the 100s.
$flow_worlduvscale <float>
(in all games since)
- The number of times the flow map fits into the material. Face texture scale affects this.
$flow_uvscrolldistance <float>
(in all games since)
- 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)
- 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)
- How rough the surface of the water is.
$flow_noise_texture <texture>
(in all games since)
- A treatment texture used to break up repetition of the normal map.
$flow_noise_scale <float>
(in all games since)
- How many times to fit the noise texture into the normal map. Typically around 0.01.
$flow_debug <bool>
(in all games since)
- 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.
Basetexture Flow
$basetexture <texture>
(in all games since)
- A "sludge layer", used in
for the sludge in the test chambers. The alpha channel of the
$basetexture
controls the strength of the reflection; darker values are more reflective, while lighter values are less reflective. $color_flow_uvscale <float>
(in all games since)
- 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)
- Time needed for the base texture to cross the
$color_flow_uvscrolldistance
. $color_flow_uvscrolldistance <float>
(in all games since)
- 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)
- How sharp the transition should be between repeats, should be 1.
- To do: Better explanation
$color_flow_displacebynormalstrength <float>
(in all games since)
- How much the normal map affects the base texture. Uses extremely low values, usually 0.01 or less.
Authoring a flow map
Overall, trying to create a flow map manually is a nightmare. Painting the flowmap, 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)
- There are now tools to assist in painting flowmaps.
- Flow field editor from algoholic.eu : http://algoholic.eu/another-flow-field-editor-update/
- 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
Other
%compilewater <bool>
- This is needed to make a map using the material compile properly.
$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.
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.
See also
- Adding Water (in Hammer)
- Creating a Waterfall Material
- Making a wall of water
- True reflections under CSS (French)