Q3MAP Shader Reference

Specifies how to use the surface as a sky, including an optional far box (stars, moon, etc), optional cloud layers with any shader attributes, and an optional near box (mountains in front of the clouds, etc).

farbox

Specifies a set of files to use as an environment box behind all cloudlayers. Specify "-" for no farbox, or a file base name. A base name of "env/test" would look for files "env/test_rt.tga", "env/test_lf.tga", "env/test_ft.tga", "env/test_bk.tga", "env/test_up.tga", "env/test_dn.tga" to use as the right, left, front, back, up, and down sides.

cloudheight

Controls apparent curvature of the cloud layers - lower numbers mean more curvature (and thus more distortion at the horizons). Higher height values create "flatter" skies with less horizon distortion. Think of height as the radius of a sphere on which the clouds are mapped. Good ranges are 64 to 256. The default value is 128.

nearbox

Specified as farbox, to be alpha blended ontop of the clouds. This has not be tested in a long time, so it probably doesn't actually work. Set to "-" to ignore.

Design Notes:

If you are making a map where the sky is seen by looking up most of the time, use a lower cloudheight value. Under those circumstances the tighter curve looks more dynamic. If you are making a map where the sky is seen by looking out windows most of the time or has a map area that is open to the sky on one or more sides, use a higher height to make the clouds seem more natural.

It is possible to create a sky with up to 8 cloudlayers (I don't think this is a physical limit, more of a practical one - see below), but that also means 8 processing passes and a potentially large processing hit.

Be aware that the skybox does not wrap around the entire world. The "floor" or bottom face of the skybox is not drawn by the game. If a player in the game can see that face, they will see the "hall of mirrors" effect.

There's a bug in Quake 3 (but fixed in Enemy Territory) that causes a shader vertex overflow (SHADER_MAX_VERTEXES HIT IN FILLCLOUD SKY SIDE) if too many cloud layers are used in maps with a lot of visible sky. To compensate, either reduce the amount of visible sky or limit the shader to two cloud layers. Q3Map2 sky portals may be a good alternative if you feel a standard sky isn't interesting enough.

Q3Map2 sky shaders work differently from the original and contain a number of improvements in terms of efficiency and visually. The example given below is an original Quake III Arena sky shader. While it is still operational, it is a little outdated and is being kept here for legacy purposes only. It is recommended that you take advantage of the new features of Q3Map2 skies by consulting Appendix: Light Emitting Shaders. Below is an example of a default (pre-Q3Map2) Quake 3 sky shader.

textures/skies/xtoxicsky_dm9
{
        qer_editorimage textures/skies/toxicsky.tga
        surfaceparm noimpact
        surfaceparm nolightmap
        q3map_globaltexture
        q3map_lightsubdivide 256
        q3map_surfacelight 400
        surfaceparm sky
        q3map_sun 1 1 0.5 150 30 60
        skyparms full 512 -
        {
                map textures/skies/inteldimclouds.tga
                tcMod scale 3 2
                tcMod scroll 0.1 0.1
        }
        {
                map textures/skies/intelredclouds.tga
                blendFunc add
                tcMod scale 3 3
                tcMod scroll 0.05 0.05
        }
}

Every surface of a polygon has two sides, a front and a back. Typically, we only see the front or "out" side. For example, a solid block you only show the front side. In many applications we see both. For example, in water, you can see both front and a back. The same is true for things like grates and screens.

To "cull" means to remove. The value parameter determines the type of face culling to apply. The default value is cull back if this keyword is not specified. However for items that should be inverted then the value front should be used. To disable culling, the value disable or none should be used. Only one cull instruction can be set for the shader.

front

The front or "outside" of the polygon is not drawn in the world. It is used if the keyword "cull" appears in the content instructions without a side value.

back

Cull back removes the back or "inside" of a polygon from being drawn in the world.

disable or none

Neither side of the polygon is removed. Both sides are drawn in the game. Very useful for making panels or barriers that have no depth, such as grates, screens, metal wire fences and so on and for liquid volumes that the player can see from within. Also used for energy fields, sprites, and weapon effects (e.g. plasma).

Design Notes:

For things like grates and screens, put the texture with the cull none property on one face only. On the other faces, use a non-drawing texture.

This function performs a general deformation on the surface's vertexes, changing the actual shape of the surface before drawing the shader passes. You can stack multiple deformVertexes commands to modify positions in more complex ways, making an object move in two dimensions, for instance. There are 6 possible values for the type parameter, each of which will be described in more detail: wave, normal, bulge, move, autosprite, autosprite2. Depending on which of the 6 type parameters are used, different additional parameters will need to be used, including the generalized waveform functions (see Introduction: Key Concepts).

Design Notes:

The div and amplitude parameters, when used in conjunction with liquid volumes like water should take into consideration how much the water will be moving. A large ocean area would have have massive swells (big div values) that rose and fell dramatically (big amplitude values). While a small, quiet pool may move very little.

deformVertexes wave div func base amplitude phase freq

Designed for water surfaces, modifying the values differently at each point. The div parameter is used to control the wave "spread" - a value equal to the q3map_tessSize of the surface is a good default value. It accepts the standard wave functions sin, triangle, square, sawtooth or inversesawtooth.

deformVertexes normal div func base amplitude freq

This deformation affects the normals of a vertex without actually moving it, which will effect later shader options like lighting and especially environment mapping. If the shader stages don't use normals in any of their calculations, there will be no visible effect. The div parameter is used to control the wave "spread" - a value equal to the q3map_tessSize of the surface is a good default value. Good values for amplitude ranges from 0.1 to 0.5 while values of 1.0 to 4.0 are good for frequency.

Design Notes:

Putting values of 0.1 to 0.5 in Amplitude and 1.0 to 4.0 in the Frequency can produce some satisfying results. Some things that have been done with it: A small fluttering bat, falling leaves, rain, flags.

deformVertexes bulge bulgeS bulgeT bulgeSpeed

This forces a bulge to move along the given s and t directions. Designed for use on curved pipes. The bulgeS and bulgeT parameters is the amount of bulge displacement measured in game units. bulgeSpeed is the number of seconds it takes for the bulge to complete a single cycle.

deformVertexes move x y z func base amplitude phase freq

The move parameter is used to make a brush, curve patch or model appear to move together as a unit. The x y z values are the distance and direction in game units the object appears to move relative to it's point of origin in the map. The func base amplitude phase freq values are the same as found in other waveform manipulations.

The product of the function modifies the values x, y, and z. Therefore, if you have an amplitude of 5 and an x value of 2, the object will travel 10 units from its point of origin along the x axis. This results in a total of 20 units of motion along the x axis, since the amplitude is the variation both above and below the base.

It must be noted that an object made with this shader does not actually change position, it only appears to.

Design Notes:

If an object is made up of surfaces with different shaders, all must have matching deformVertexes move values or the object will appear to tear itself apart.

deformVertexes autosprite

This function can be used to make any given triangle quad (pair of triangles that form a square rectangle) automatically behave like a sprite without having to make it a separate entity. This means that the "sprite" on which the texture is placed will rotate to always appear at right angles to the player's view as a sprite would. Any four-sided brush side, flat patch, or pair of triangles in a model can have the autosprite effect on it. The brush face containing a texture with this shader keyword must be square.

deformVertexes autosprite2

Is a slightly modified "sprite" that only rotates around the middle of its longest axis. This allows you to make a pillar of fire that you can walk around, or an energy beam stretched across the room.

Fogparms describes how to render the fog on the surfaces. You must also specify "surfaceparm fog" to cause Q3Map2 to identify the surfaces inside the volume.

r g b

These are normalized values. A good computer art program should give you the RGB values for a color. To obtain the values that define fog color for Quake III Arena, divide the desired color's red, green and blue values by 255 to obtain three normalized numbers within the 0.0 to 1.0 range.

opacity

This is the distance, in game units, until the fog becomes totally opaque, as measured from the point of view of the observer. By making the height of the fog brush shorter than the distance to opaque, the apparent density of the fog can be reduced (because it never reaches the depth at which full opacity occurs).

Fog volume brushes must obey the following rules:

• The fog volume can only have one surface visible (from outside the fog).
• Fog must be made of one brush. It cannot be made of adjacent brushes.
• Fog brushes must be axial. This means that only square or rectangular brushes may contain fog, and those must have their edges drawn along the axes of the map grid (all 90 degree angles).

Design Notes:

If a water texture contains a fog parameter, it must be treated as if it were a fog texture when in use.

If a room is to be filled completely with a fog volume,it can only be entered through one surface (and still have the fog function correctly).

Additional shader passes may be placed on a fog brush, as with other brushes.

This causes the texture to ignore user-set values for the r_picmip cvar command. The image will always be high resolution. Example: Used to keep images and text in the heads up display from blurring when user optimizes the game graphics.

This implies noPicMip, but also prevents the generation of any lower resolution mipmaps for use by the 3D card. This will cause the texture to alias when it gets smaller, but there are some cases where you would rather have this than a blurry image. Sometimes thin slivers of triangles force things to very low mipmap levels, which leave a few constant pixels on otherwise scrolling special effects.

Surfaces rendered with the polygonOffset keyword are rendered slightly off the polygon's surface. This is typically used for wall markings and "decals." The distance between the offset and the polygon is fixed. It is not a variable in Quake III Arena.

Design Notes:

Use this for wall or floor markings, particularily for direction arrows for team games. Texture the brush with the decal shader on one face and the other faces with a nodraw shader. Then place the brush flush with the surface of the wall or floor.

When using a _decal entity for texture projection, polygonOffset must be used to prevent Z-fighting. If you experience problems with depth sorting, try using sort 6.

Specifies that this texture is the surface for a portal or mirror. In the game map, a portal entity must be placed directly in front of the texture (within 64 game units). All this does is set "sort portal", so it isn't needed if you specify that explicitly.

Use this keyword to fine-tune the depth sorting of shaders as they are compared against other shaders in the game world. The basic concept is that if there is a question or a problem with shaders drawing in the wrong order against each other, this allows the designer to create a hierarchy of which shader draws in what order.

The default behavior is to put all blended shaders in sort "additive" and all other shaders in sort "opaque", so you only need to specify this when you are trying to work around a sorting problem with multiple transparent surfaces in a scene.

The value here can be either a numerical value or one of the keywords in the following list (listed in order of ascending priority):

portal (1)

This surface is a portal, it draws over every other shader seen inside the portal, but before anything in the main view.

Sky (2)

Typically, the sky is the farthest surface in the game world. Drawing this after other opaque surfaces can be an optimization on some cards. This currently has the wrong value for this purpose, so it doesn't do much of anything.

Opaque (3)

This surface is opaque (rarely needed since this is the default with no blendfunc)

Banner (6)

Transparent, but very close to walls.

Underwater (8)

Draw behind normal transparent surfaces.

Additive (9)

Normal transparent surface (default for shaders with blendfunc's)

Nearest (16)

This shader should always sort closest to the viewer, e.g. muzzle flashes and blend blobs.

Currently takes a single function, const. This directive is used to set a surfaces vertex alpha values. q3map_alphaGen operations are applied to an object's vertexes so the rgbGen vertex directive is required for each affected stage.

q3map_alphaGen const norm

Forces a fixed vertex alpha value to the entire shader surface, useful for controlling transparency or blending. Values are a normalized number.

This is used for special vertex alpha blending effects on surfaces by altering the vertex alpha values depending on specific surface properties, such as the surfaces normal axis or the vertexes contained within its volume. q3map_alphaMod operations are applied to an object's vertexes so the rgbGen vertex directive is required for each affected stage.

q3map_alphaMod dotproduct ( X Y Z )

Used to blend textures using alphaFunc or blendFunc in the shader's second pass, with the transparency depending on the surface's normal axis vector. This is achieved by taking the user specified vector ( X Y Z ) and applying a dotproduct calculation with the generated vertex normal vector to yield a normalized vertex alpha value. The dot product operation multiplies each element of one vector against the corresponding elements of a second vector, then adds them:

( 0 0 1 ) dp ( 0 0 1 ) = 0 * 0 + 0 * 0 + 1 * 1 = 1
( 0 0 1 ) dp ( 0 0 0.5 ) = 0 * 0 + 0 * 0 + 1 * 0.5 = 0.5
( 0.5 0.5 1 ) dp ( 0 0.5 0.5 ) = 0.5 * 0 + 0.5 * 0.5 + 1 * 0.5 = 0.75

In a practical sense, you can think of the dotproduct vector ( 0 0 0.9 ) as meaning that all vertex normal vectors pointing straight up along the z-axis ( 0 0 1 ) will have a vertex alpha value of 90% opacity.

q3map_alphaMod dotproduct2 ( X Y Z )

This works in a similar way to dotproduct except it exaggerates the differences in vertex normals by squaring the final dot product value. With the same values as the above example, dotproduct2 would give the following:

[ ( 0 0 1 ) dp ( 0 0 1 ) ]2 = ( 0 * 0 + 0 * 0 + 1 * 1 )2 = 1
[ ( 0 0 1 ) dp ( 0 0 0.5 ) ]2 = ( 0 * 0 + 0 * 0 + 1 * 0.5 )2 = 0.25
[ ( 0.5 0.5 1 ) dp ( 0 0.5 0.5 ) ]2 = ( 0.5 * 0 + 0.5 * 0.5 + 1 * 0.5 )2 = 0.5625

Example q3map_dotproduct shader for terrain:

textures/shaderlab_vector_1/rock_1_z_lodterrain
{
        //Used for radiosity lighting
        q3map_lightImage textures/shaderlab_vector_1/rock_1.tga

        q3map_nonplanar
        q3map_shadeAngle 179
        q3map_tcGen ivector ( 512 0 0 ) ( 0 512 0 )
        q3map_tcMod rotate 33
        q3map_lightmapAxis z

        // this means dot product squared, for faster falloff between vertical and horizontal planes
        q3map_alphaMod dotproduct2 ( 0 0 0.95 )

        surfaceparm nonsolid
        surfaceparm pointlight

        {
                map textures/shaderlab_vector_1/rock_1.tga
                rgbGen vertex
        }
        {
                map textures/slterra/sand_1.tga
                blendFunc GL_SRC_ALPHA GL_ONE_MINUS_SRC_ALPHA
                rgbGen vertex
        }
}

Design Notes:

Typical examples of use include snow covering the top faces of objects, or terrain with grass growing on horizontal planes blending into rocky cliffs on near vertical surfaces. It is an excellent way of automatically creating realistic alpha-blended terrain without the complicated steps of setting up an alpha map.

q3map_alphaMod scale norm

Used in conjunction with q3map_alphaMod volume. Scales the vertex alpha by the specified normalized number value.

q3map_alphaMod set norm

Used in conjunction with q3map_alphaMod volume. Sets the vertex alpha (regardless of any previous alpha values) to the specified normalized number value.

q3map_alphaMod volume

This was created as a way to explicitly set or modify the vertex alpha values of vertex points contained within a controlling brush volume marked with this shader directive. Applies all other q3map_alphaMod directives to each vertex inside a brush textured with this shader, allowing large faded scrolling fire shaders, waterfalls, marquees, explicit dotProduct terrain blending control, etc.

Design Notes:

This is usually used in special alphaMod volume "common" shaders for use within the editor only. A brush textured with the alphaMod volume shader is used to overlap the vertexes of another brush or model using an alpha-blended shader, altering the vertex alpha values. Worldspawn alphaMod volume brushes will affect all surfaces it comes in contact with. You can func_group an alphaMod volume brush to its affecting brush to localize the blend to just that entity.

This allows a brush to use a different shader when you are inside it looking out. By way of example, this would allow a water brush (or other) surfaces to have a different sort order or appearance when seen from the inside. q3map_backShader only works on brush faces. For this reason, it is often deprecated in favor of using q3map_cloneShader where the target shader contains q3map_invert. It can still be useful as a kind of shorthand.

A surface light is lit by itself, often causing areas of higher light intensity than other areas. q3map_backSplash moves the light source away from the surface of the shader, allowing it to create smoother lighting over the face. By default, all shaders are assigned backsplash values, 5 for percentage, 23 units for distance.

percentage

Specifies the intensity percentage of the light generated by q3map_surfacelight to be redirected back at the surface. Use a value of 0 or a negative value to disable back splash lights.

distance

Distance of the back splash lights from the surface.

Allows shaders to be subclassed (Q3Map2 relevant portions only, such as surfaceparms, lighting, texture projection, etc). Subclassed shaders can reference the base shader by referring to the base shader's name. In order for q3map_baseShader to work correctly, the base shader must be specified before any shaders that subclass it. Some EasyGen terrain templates incorrectly specified the base shader after the terrain shaders that depended on it, resulting in some interesting errors.

This is fundamentally the reverse of q3map_remapShader. Use q3map_baseShader when a single group of q3map_* directives is required for multiple base shaders. Use q3map_remapShader when similar shaders are used that require different groups of q3map_* directives.

Deprecated! Use q3map_bounceScale instead.

Takes positive decimal number values between 0 and 1.0 (or higher), to scale the amount of light reflected in radiosity passes. You can oversaturate it by using a number higher than 1.0, but this can lead to excessive compile times. Using 90 would probably make things positively glacial. 1.0 is a default, fudged number that looked OK with the maps that were tested. Tweaking it to 1.5 or 2.0 won't hurt anything per se, but it does give you finer control over how each shader re-emits light. The poorly worded q3map_bounce has been renamed to q3map_bounceScale. While its use has been deprecated, q3map_bounce still works.

Automatically clips misc_model entities for player and weapon collision. This should only be used on large models such as terrain (not small decorative models - manually clip those). The shader's surfaceparms are inherited by the magic clip brush, so if you have surfaceparm nonsolid in your model's shader that uses q3map_clipModel, then the brush will also be non-solid. This can also be set on a per model basis with the entity key/value pair, spawnflags 2.

A shader with this directive will inherit the target shader's properties and appearance. Be careful, this can lead to an infinite loop if a cloning shader references another cloning shader or itself.

Currently takes a single function, const. This directive is used to set a surfaces vertex color values. q3map_colorGen operations are applied to an object's vertexes so the rgbGen vertex directive is required for each affected stage. Same as q3map_rgbGen.

q3map_colorGen const ( R G B )

Forces a fixed vertex color value to the entire shader surface.

Used to alter the vertex color values of vertexes contained within its volume. q3map_colorMod operations are applied to an object's vertexes so the rgbGen vertex directive is required for each affected stage. Possible uses include creating a neutral hued texture for a CTF middleground and then creating shader instances of the texture for red and blue bases. Same as q3map_rgbMod.

q3map_colorMod scale ( R G B )

Used in conjunction with q3map_colorMod volume. Scales the vertex color by the specified color values.

q3map_colorMod set ( R G B )

Used in conjunction with q3map_colorMod volume. Sets the vertex color to the specified color values.

q3map_colorMod volume

This was created as a way to explicitly set or modify the vertex color values of vertex points contained within a controlling brush volume marked with this shader directive. Applies all other q3map_colorMod directives to each vertex inside a brush textured with this shader to change the hue of the affected surface.

Design Notes:

This is usually used in special colorMod volume "common" shaders for use within the editor only. A brush textured with the colorMod volume shader is used to overlap the vertexes of another brush or model, altering the vertex color values. Worldspawn colorMod volume brushes will affect all surfaces it comes in contact with. You can func_group a colorMod volume brush to its affecting brush to localize the hue to just that entity.

Specifies the direction a fog shader fades from transparent to opaque. Values indicate a directional vector.

Forces model (MD3, ASE, etc.) surfaces to be broken down into their component triangles like brush faces and passed through the meta code on a per shader basis. This is required for lightmapped models. Setting spawnflags 4 on a misc_model will set q3map_forceMeta on all its surfaces.

Obsolete! By default, no sunlight is cast on vertex-lit .md3 models or vertex-lit terrain. Using this option, sunlight (overbright bits created by the q3map_sun option) will be cast on these surfaces. q3map_forceSunlight is now obsolete since suns are now first class light sources.

This is used for generating fur over a surface. This is typically used in conjunction with q3map_cloneShader in the surface (parent) shader and references the fur shader as the clone. A possible application of this is to create grass on alphablended terrain. Keep in mind that the use of a fur shader may cause a large hit to performance but when used sparingly, it can produce some interesting effects. (See Appendix: Fur)

layers

This specifies the number of desired replicated fur layers generated.

offset

The distance (in game units) between subsequent layers.

fade

A normalized value indicating the fade falloff between subsequent layers.

Use this shader in the global directive commands whenever the tcMod scale function is used in one of the later render stages. Many problems with getting shader effects to work across multiple adjacent brushes are a result of the way Q3Map2 optimizes texture precision. This option resolves that, but at the expense of some precision of the textures when they are far away from the origin of the map.

This is used for explicit terrain-style indexed mapping. It instructs Q3Map2 to look at the func_group terrain entity's _indexmap key for an image to pull index values from, and then to construct a shader name with the root based on the _shader key's value.

Inverts a surface normal. Works on brush faces, models and patches. Used in celshading to achieve the inverted backfacing hull. Can be used with a shader that is targeted by q3map_cloneshader for something similar to q3map_backShader.

By default, surface lights use the average color of the source image to generate the color of the light. q3map_lightImage specifies an alternate image to be used for light color emission, radiosity color emission, light filtering and alpha shadows. You can even use a light image with a different alpha channel for blurrier alpha shadows. The light color is averaged from the referenced texture. The texture must be the same size as the base image map. q3map_lightImage should appear before qer_editorImage.

The reason q3map_lightImage is specified for the light in the example below, is because the blend map is predominantly yellow, but the base image is not. The designer wanted the color of the light to be sampled from the blend map instead of the base image.

textures/eerie/ironcrosslt2_10000
{
        // this TGA is the source for the color of the blended light
        q3map_lightImage textures/gothic_light/ironcrosslt2.blend.tga

        //editor TGA (used because the shader is used with several different light values)
        qer_editorImage textures/gothic_light/ironcrosslt2.tga

        //emitted light value of 10,000
        q3map_surfacelight 10000

        {
                //source texture is affected by the lightmap
                map $lightmap

                // this command handles the overbright bits created by "sunlight" in the game
                rgbGen identity
        }
        {
                map textures/gothic_light/ironcrosslt2.tga
                blendFunc filter
                rgbGen identity
        }
        {
                map textures/gothic_light/ironcrosslt2.blend.tga
                blendFunc add
        }
}

Takes a single argument: either x, y or z as the direction from which the lightmap is projected from. The directive q3map_terrain has an implicit (read default) q3map_lightmapAxis defined as z. This directive is not recommended for things like caves or arches which have undersides.

Lightmap brightness scaling. A value of 2.0 will be twice as bright (linearly) and a value of 0.5 will be half as bright.

This is usually used on light emitting shaders to approximate finer subdivided lighting. It adds a gaussian blur effect to the lightmaps of either the shader itself, or the surfaces affected by the shader, or both. The values for self and other are measured in world units of filtering (blurring) of lightmap data cast by any light sources.

self

Amount of blur set for the shader itself to approximate for the surfacelight's finer subdivided lighting. It should be set to 0 for sky shaders since they don't have lightmaps.

other

Amount of blur set for other surfaces affected by this shader's emitted light. It should be set just high enough to eliminate the "stadium shadow" effect sometimes produced by q3map_skylight or to smooth out the lighting on surfacelights.

If using a value higher than 4 for the iterations parameter on q3map_skylight, you don't need q3map_lightmapFilterRadius as much, but at the expense of higher compile times. q3map_lightmapFilterRadius should be placed before any light related shader directives that you want it to affect. (see Appendix: Light Emitting Shaders)

Deprecated! Use q3map_lightmapBrightness instead.

Allows surfaces like terrain to be mapped onto a single lightmap page for seamless terrain shadows. It will specify that the shaders using it can merge nonplanars together onto a single lightmap, so you can have a single 512x512 lightmap across a terrain entity. Note that most id Tech 3 engine games are limited to lightmap pages of 128x128. You may need to experiment with q3map_lightmapSize and the Q3Map2 -export general switch.

Takes a single parameter, defaulting to 1.0, which specifies how many units off a surface should Q3Map2 sample lighting from. Use larger values (2.0-8.0) if you're getting ugly splotches on lightmapped terrain. Try to use filtering to solve splotches if possible, leaving q3MaplightmapSampleOffset as a last resort.

Surfaces using a shader with this option will have the pixel size of the lightmaps set to N world grid units. This option can be used to produce high-resolution shadows on certain surfaces. In addition, it can be used to reduce the size of lightmap data, where high-resolution shadows are not required, gaining memory and performance benefits. The default Quake III lightmap sample size is 16, smaller numbers increases lightmap resolution. In general, you should stick with power of 2 values.

Specifies the size of the lightmap page that surface lightmaps get packed on to. Used mainly in Enemy Territory for terrain lightmaps (512x512) in concert with the Q3Map2 switch -lightmapsize. Most idTech 3 games will only support internal lightmap pages of 128x128. Larger pages will result in lightmaps exported externally from the .bsp file.

This forces a specified color of light to be emitted from a surface or sky light, rather than sampling colors from a lightimage, editor image or the texture map. Three normalized color values of light are required for the red green blue parameters. This does not affect bounced light in radiosity or lightfilter.

Used to set light styles on surface lights for lightmap flickering/waveform effects. N takes the form of a number between 1 and 31, that references the corresponding style number set in the worldspawn entity. Equivalent to setting "style" "N" on a light entity (see Appendix: Lightstyles).

Used on surface lights (see q3map_surfacelight). Controls the distance between surface generated light sources for uniform lighting. It defaults to 120 game units, but can be made larger or smaller as needed (for light surfaces at the bottom of cracks, for example). This can be a dominant factor in processing time for Q3Map2 lighting. Can have an increasingly "darker" effect when used with -fast. Compensate by raising the surface light value. For sky shaders, use q3map_skylight instead (see Appendix: Light Emitting Shaders).

You might have noticed that terrain has been made to not clip or t-junction anymore. It was causing too many issues, so a new parameter was added: q3map_noClip. Normally, Q3Map2 clips all faces to the BSP, and then takes the minimum polygon that encompasses all visible fragments. q3map_noClip forces Q3Map2 to uses the original brush faces (This is implicit for autosprite(2) surfaces). Therefore, if you map tidy, you could theoretically use q3map_noClip on all your shaders. q3map_noClip and q3map_noTJunc, when used in combination, will preserve mesh geometry exactly as you make it.

When used on surfaces that emit light, this will disable -fast optimizations. This is useful for large areas of dim sky, where you want the dim light to reach all surfaces. This shader directive prevents fast from affecting dim sky surfaces. It is necessary, if you can't do a workaround with brighter skies or by using a larger q3map_lightSubdivide value.

Volumes marked with a shader containing this directive will not be affected by fog. For example, it can be used on sky shaders to prevent the fog from affecting it.

Instructs Q3Map2 to merge any adjacent triangles that don't lie in the same plane into a non-planar triangle soup. This allows shadows to be cast correctly across non-planar edges. It is typically used on lightmapped terrain shaders.

Allow the use of a normal (height) map to simulate textured bumpmapping. This isn't real bumpmapping per se, but generates a static lightmap image that reflects the normal map and light source.

Read as "no T-Junc". With this option, surfaces modified by a shader are not used for T-junction fixing. q3map_noClip and q3map_noTJunc, used in combination will preserve mesh geometry exactly as you make it.

Suppresses Q3Map2 from overwriting the BSP-phase set vertex RGB values.

Obsolete! Vertex lighting code was rewritten a couple of times, rendering this directive irrelevant. Shaders that are used on misc_models or terrain were to use q3map_noVertexShadows to disable shadows being cast on the vertex lit surfaces. Casting shadows at small, misc_model objects often makes sense. However, having shadows on large, vertex lit terrain surfaces often looks bad. Shadows are not cast on forced_vertex_lit surfaces by default (shaders with pointlight).

Offsets a surface along the vertex normals by N.N units. Used in celshading for those black edges.

Obsolete! When this option is used in conjunction with the original lighting algorithm (-light), surfaces with textures modified with this option will show shadows that are cast by curve patches. Curve patches do not cast shadows by default. You would usually force patches to cast shadows by using the -patchshadows Q3Map2 switch.

Allows shaders to be subclassed. Subclassed shaders can reference the remap shader by referencing the remap shader's name. In order for this to work, the remap shader must be specified before any shaders that references it. Subclassed shaders must contain Q3Map2 and editor relevant portions only (q3map_*, surfaceparm and qer_* directives).

This is fundamentally the reverse of q3map_baseShader. Use q3map_baseShader when a single group of q3map_* directives is required for multiple base shaders. Use q3map_remapShader when similar shaders are used that require different groups of q3map_* directives.

Design Notes:

Since the subclassed shaders that are applied to geometry does not contain any texture stages, qer_editorImage is usually required in conjunction with q3map_remapShader.

Same as q3map_colorGen

Same as q3map_colorMod

Specifies the breaking angle for phong shading. This allows for smooth shadows between brush faces like patches. The angle parameter is the angle between adjacent faces at which smoothing will start to occur. Typical values are usually in the 120-179 range.

This replaces q3map_surfacelight and q3map_lightSubdivide on sky surfaces for much faster and more uniform sky illumination. Amount is a brightness value, similar to what you would use in q3map_sun. Good values are between 50 and 200. Iterations is an exponential factor. 3 is the best value that balances speed and quality. Values of 4 and 5 are higher quality at the expense of higher compile time. Values below 3 are not too useful. See Appendix: Light Emitting Shaders.

This is used on lightmapped model shaders if splotched lighting artifacts appear. Any shadows at the ambient/dark level will be flooded from neighbouring luxels. This gets rid of shadow acne, but a surface must be more or less uniformly lit or this looks ugly. Try using q3map_lightmapSampleOffset first before using this as a last resort.

For use on shaders that accompany style lights. For any shaders that may be hit by a styled light, add q3map_styleMarker after the lightmap stage and before the texture stages so Q3Map2 can properly create the fake lightmap stages (see Appendix: Lightstyles).

Similar to q3map_styleMarker except it is used on masked textures where a depthFunc equal is required.

This directive in a sky shader will create the illusion of light cast into a map by a single, infinitely distance parallel light source (sun, moon, hellish fire, etc.). This is only processed during the lighting phase of Q3Map2. While still perfectly usable, q3map_sun is now deprecated in favour of q3map_sunExt (see below).

Works like q3map_sun with the addition of two new parameters to create "light jittering" for penumbra (half-shadow) effects. This gives you much more realistic shadows from the sun, especially when trying to simulate a cloudy day or a wide sun. The penumbra effect can also be applied to entity lights (point, spot or sun) with the _deviance N (distance in world units for point/spot lights and degrees for suns) and _samples N (number of samples) key/value pairs.

red green blue

Color is described by three normalized RGB values. Color will be normalized to a 0.0 to 1.0 range, so it doesn't matter what range you use.

intensity

The brightness of the generated light. A value of 100 is a fairly bright sun. The intensity of the light falls off with angle but not distance.

degrees

The angle relative to the directions of the map file. A setting of 0 degrees equals east. 90 is north, 180 is west and 270 is south. In the original version of Q3Map, non-axial values had a tendency to produce jagged shadows. With Q3Map2, this problem is avoided with new options like lightmap filtering, raytracing and penumbra effects.

elevation

The distance, measured in degrees from the horizon (z value of zero in the map file). An elevation of 0 is sunrise/sunset. An elevation of 90 is noon.

deviance

The number of degrees for the half-shadow. General values up to 2 or 3 are acceptable. The real sun has a solid angle of about half a degree.

samples

The number of random jitters distributed over the solid arc (~16).

Design Notes:

Sky shaders should probably still have a q3map_surfacelight or preferred q3map_skylight value. The "sun" gives a strong directional light, but doesn't necessarily give the fill light needed to soften and illuminate shadows. Skies with clouds should probably have a weaker q3map_sun value and a higher q3map_surfacelight or q3map_skylight value. Heavy clouds diffuse light and weaken shadows. The opposite is true of a cloudless or nearly cloudless sky. In such cases, the "sun" or "moon" will cast stronger shadows that have a greater degree of contrast. This is also why q3map_sunExt is preferred. It gives the designer greater control over shadow contrast with a penumbra effect.

Design Notes:

Not certain what color formula you want to use for the sun's light? Try this. Create a light entity. Use the Radiant editor's color selection tools to pick a color. The light's _color key's value will be the normalized RGB formula. Copy it from the value line in the editor (CTRL+c) and paste it into your shader.

The texture gives off light equal to the value set for it. The relative surface area of the texture in the world affects the actual amount of light that appears to be radiated. To give off what appears to be the same amount of light, a smaller texture must be significantly brighter than a larger texture. Unless the q3map_lightImage or q3map_lightRGB directive is used to select a different source for the texture's light color information, the color of the light will be the averaged color of the texture. For sky shaders, use q3map_skylight instead for faster and more uniform sky illumination.

A surface with q3map_surfaceModel in its shader will randomly place a specified model across it's face. This is designed to place grass or tree models over terrain.

modelpath

The path to the model file (any supported format).

density

The density of the models, in game units.

odds

The odds of the model appearing (normalized?).

minscale

The minimum scale of the model from its original size of 1.0.

maxscale

The maximum scale of the model from its original size of 1.0.

minangle

The model's minimum angle of rotation.

maxangle

The model's maximum angle of rotation.

oriented

This is a flag, either 0 or 1, and sets whether the model gets fitted to the orientation of the surface.

This currently supports two functions, vector and ivector. Both functions are used for texture projection and do the exact same thing. The only difference is in the math, ivector was designed to be more intuitive.

q3map_tcGen vector sVector tVector

Projects a texture Ns units by Nt units along a chosen axis. q3map_tcGen vector ( 1/256 0 0 ) ( 0 1/256 0 ) will project a texture every 256 units in x, and every 256 units in y, along the z-axis.

q3map_tcGen ivector 1.0/sVector 1.0/tVector

Projects a texture Ns units by Nt units along a chosen axis. q3map_tcGen ivector ( 256 0 0 ) ( 0 256 0 ) will project a texture every 256 units in x, and every 256 units in y, along the z-axis. Ivector means inverse vector, and this means you won't have to do the divide with a calculator. Inverse = 1.0/n, unless the value is 0, then the matrix value is set to 0. A bit of dodgy math, but it works.

This works in a similar manner to the stage specific tcMod directive (see Stage Directives: tcMod), except in the compiler, so that modified texture coordinates are "baked" into the surface. This lets you set up less obvious texture tiling on natural and organic surfaces (especially terrain).

q3map_tcMod rotate degrees

Rotates the texture (around origin, not center) a specified number of degrees.

q3map_tcMod scale s-scale t-scale

Scales S (x) and T (y) texture co-ordinates. scale 2 2 would halve the size of the texture (doubling the texture co-ordinates).

q3map_tcMod translate or move or shift s-offset t-offset

Shifts texture co-ordinates by S, T amount. translate 0.5 0 would shift it one-half in S, and none in T.

Alphamap terrain shaders (typically textures/common/terrain and terrain2) must have the q3map_terrain directive. Terrain is handled completely differently from previous versions. Q3Map2 no longer looks for the word terrain in the shader name to determine whether or not it is an indexed shader. It looks for q3map_indexed, or q3map_terrain, which then sets off a bunch of stuff shoehorned into it, like: the lightmap axis, texture projection, etc.

By default, q3map_terrain sets the following:

q3map_tcGen ivector ( 32 0 0 ) ( 0 32 0 )
q3map_lightmapAxis z
q3map_nonplanar
q3map_shadeAngle 180 //(maybe 175?)
q3map_indexed

This controls the tessellation size (how finely a surface is chopped up in to triangles), in game units, of the surface. This is only applicable to solid brushes, not curves, and is generally only used on surfaces that are flagged with the deformVertexes directive. Abuse of this can create a huge number of triangles. This happens during Q3Map2 processing, so maps must be reprocessed for changes to take effect. The poorly named tessSize directive still works but has been deprecated in favour of q3map_tessSize for consistency.

Design Notes:

It can also be used on tessellating surfaces to make sure that tessellations are large and thus, less costly in terms of triangles created.

Deprecated. Useful when you don't specify an editor or light image for a shader. Recent builds of Q3Map2 will find some referenced image in a shader and use that as a fallback. Historically, this was used for surface splitting for RTCW for PS2, to accommodate the hardware's limited texture range precision.

Obsolete! Surfaces using a shader with this option will always be lit with the original light algorithm. Patches will not cast shadows on this surface, unless the shader option q3map_patchShadows is also used.

The light value, at the vertices of a surface using a shader with this option, is multiplied by the scale value. This is a way to lighten, or darken, a vertex_lit surface, in comparison to other lightmap_lit surfaces around it. Values must be normalized.

Obsolete! (See q3map_noVertexShadows) By default, no shadows are cast on vertex_lit_surfaces (see surfaceparm pointlight). In addition, when running Quake III Arena in vertex light, no shadows are cast upon any surface at all, since shadows are part of the lightmap. When using this shader directive, shadows will be cast on surfaces that are vertex lit. However, sharp shadow edges won't be seen on the surfaces, since light values are only calculated at the vertices.

Obsolete!

This keyword applied to a texture on a brush, patch or model will cause the lighting phase of the Q3Map2 process to use the texture's alpha channel as a mask for casting static shadows in the game world.

Design Notes:

Alphashadow does not work well with fine line detail on a texture. Fine lines may not cast acceptable shadows. It appears to work best with well-defined silhouettes and wider lines within the texture. Most of our tattered banners use this to cast tattered shadows.

With Q3Map2, it is possible to increase the resolution of the lightmap receiving the shadows at the cost to video memory. This can be achieved with the q3map_lightmapSampleSize keyword on the shadow receiving shader or by creating a func_group of the shadow receiving brushes and adding the _lightmapScale key with a floating-point value for the scale of the lightmap.

Works like hint brushes in that it creates BSP nodes, but unlike hint, it blocks vis by not creating a portal at the split. This is designed to be used with large terrain maps to block visibility without having to resort to tricks like sky or caulk brushes penetrating the terrain and throwing ugly shadows.

Players in part A of the map will not be able to see into part B and vice-versa. You can walk through the antiportal just fine. Note that this also blocks light. There are two caveats: They are opaque to light, and if aligned to another BSP cut (such as blocksize or the origin) they will not function correctly. Don't align it with anything else (like blocksize or another brush face) and it'll block vis. This keyword is found in "common/antiportal" so you shouldn't need to specify this. "common/antiportal" was added by ydnar, so if you're missing this shader, it is included with the latest version of Q3Map2.

A brush marked with this keyword functions as an areaportal, a break in the BSP tree. It is typically placed on a very thin brush placed inside a door entity (but is not a part of that entity). The intent is to block the game from processing surface triangles located behind it when the door is closed. It is also used by the BSPC (bot area file creation compiler) in the same manner as a clusterportal. The brush must touch all the structural brushes surrounding the areaportal. This keyword is found in "common/areaportal" so you shouldn't need to specify this.

Blocks bot movement only. Other game world entities and human players can pass through a brush marked botclip. The intended use for this is to block the bot but not other players or projectiles. This keyword is found in "common/botclip" so you shouldn't need to specify this.

Design Notes:

Careful use of botclip in a map can greatly reduce the complexity of the .aas bot navigation file, resulting in "smarter", more efficient bots.

A brush marked with this keyword function creates a subdivision of the area file (.aas) used by the bots for navigation. It is typically placed in locations that are natural breaks in a map, such as entrances to halls, doors, tunnels, etc. The intent is keep the bot from having to process the entire map at once. As with the the areaportal parameter, the affected brush must touch all the structural brushes surrounding the clusterportal. This keyword is found in "common/clusterportal" so you shouldn't need to specify this.

This surface attribute causes a brush to be ignored by the Q3Map2 process for generating possible break-points in the BSP tree. Generally speaking, detail brushes are usually set in the editor, so you shouldn't need to specify this.

Read as "do not enter". Like clusterportal, this is a bot-only property. A brush marked with donotenter will not affect non-bot players, but bots will not enter it. It should be used only when bots appear to have difficulty navigating around some map features. This does not physically stop the bot from entering a region (as with botclip). Bots will not enter the area on their own but may, for example, be blasted into the region with a rocket launcher. This keyword is found in "common/donotenter" so you shouldn't need to specify this.

Design Notes:

donotenter can be (sparingly) used in space maps around the void or around lava/slime in certain places where bots have an overwhelming tendancy to commit suicide (lemming style).

If a player lands on a surface that uses a shader with this parameter, a puff of dust will appear at the player's feet. Note that the worldspawn entity must contain the "enabledust" key with a set value of "1".

This will cue different sounds (in a similar manner to metalsteps) and cause blood to appear instead of bullet impact flashes. Actually, the code for this was never fully implemented by id Software. It remains half-finished so unfortunately it doesn't work.

fog defines the brush as being a "fog" brush. This is a Q3Map2 function that chops and identifies all geometry inside the brush. The general shader keyword fogparms must also be specified to tell how to draw the fog.

When Q3Map2 calculates the vis data, it tries to place portals in places in the map in an attempt to limit the potential viewable set (PVS). Brushes marked by a hint shader are used to manually place portals to force a break in the PVS. This keyword is found in "common/hint" so you shouldn't need to specify this.

Supposedly used to allow the player to climb vertically. This is not functional in Quake III Arena.

Assigns to the texture the game properties set for lava. This affects both the surface and the content of a brush.

Causes the Q3Map2 light stage to use the texture's RGB and alpha channels to generate colored alpha shadows in the lightmap. For example, this can be used to create the colored light effect cast by stained glass windows. This can be used with surfaceparm alphashadow.

The min/max bounds of brushes with this shader in a map will define the bounds of the map's lightgrid (model lighting). Make it as small as possible around player space to minimize bsp size and compile time. This keyword is found in "common/lightgrid" so you shouldn't need to specify this. "common/lightgrid" was added by ydnar, so if you're missing this shader, it is included with the latest version of Q3Map2.

The player sounds as if he is walking on clanging metal steps or gratings. Other than specifying flesh (doesn't work), metalsteps, nosteps, or default (i.e. specify nothing) it is currently not possible for a designer to create or assign a specific sound routine to a texture. Note: If no sound is set for a texture, then the default footsteps sound routines are heard.

Blocks monster movement. Not functional in Quake III Arena.

The player takes no fall damage if he lands onto a texture with this surfaceparm. This keyword is found in "common/cushion" but you may want to specify this on certain shaders (jump pads, for example).

Read as "No Dee-Light". A texture containing this parameter will not be affected or lit by dynamic lights, such as weapon effects. An example in Quake III Arena would be solid lava.

A texture marked with nodraw will not visually appear in the game world. Most often used for triggers, clip brushes, origin brushes, shaders with cull none or cull disable and so on. This keyword is found in "common/nodraw" so you shouldn't need to specify this.

When a player dies inside a volume (brush) marked nodrop, no weapon is dropped. The intend use is for "Pits of Death." Have a kill trigger inside a nodrop volume, and when the players die here, they won't drop their weapons. The intent is to prevent unnecessary polygon pileups on the floors of pits. This keyword is found in "common/nodrop" but you may want to specify this on certain shaders (fog volumes in pits, for example).

World entities will not impact on this texture. No explosions occur when projectiles strike this surface and no marks will be left on it. Sky textures are usually marked with this texture so those projectiles will not hit the sky and leave marks.

Projectiles will explode upon contact with this surface, but will not leave marks. Blood will also not mark this surface. This is useful to keep lights from being temporarily obscured by battle damage.

Design Notes:

Use this on any surface with a deformVertexes keyword. Otherwise, the marks will appear on the unmodified surface location of the texture with the surface wriggles and squirms through the marks.

This texture does not have a lightmap phase. It is not affected by the ambient lighting of the world around it. It does not require the addition of an rgbGen identity keyword in that stage.

The player makes no sound when walking on this texture.

This attribute indicates a brush, which does not block the movement of entities in the game world. It applied to triggers, hint brushes and similar brushes. This affects the content of a brush.

Used on the "origin" texture. Rotating entities need to contain an origin brush in their construction. The brush must be rectangular (or square). The origin point is the exact center of the origin brush. This keyword is found in "common/origin" so you shouldn't need to specify this.

Blocks player movement through a nonsolid texture. Other game world entities can pass through a brush marked playerclip. The intended use for this is to block the player but not block projectiles like rockets. This keyword is found in "common/clip" so you shouldn't need to specify this.

Design Notes:

playerclip is often useful for "smoothing" out the geometry of the map, preventing the player from snagging on objects. It is also used in open sky areas of maps, preventing the player from flying too high and seeing the "Hall of Mirrors" effect at the bottom of the cloud layer.

Surfaces using a shader with this parameter will always be vertex lit. This option can be used to reduce the lightmap data. It is often used on surfaces that don't need shadows. Basically the same as surfaceparm nolightmap.

Works just like Quake II skip texture. Use on sides of hint and antiportal brushes where you don't want BSP splits. This keyword is found in "common/skip" so you shouldn't need to specify this. "common/skip" was added by ydnar, so if you're missing this shader, it is included with the latest version of Q3Map2.

This flags the compiler, telling it that this surface should be rendered as sky.

This surfaceparm included in a texture should give it significantly reduced friction. This keyword is found in "common/slick" but you may want to specify this on certain shaders (ice, for example).

Assigns to the texture the game properties for slime. This affects both the surface and the content of a brush.

This surface attribute causes a brush to be seen by the Q3Map2 process as a possible break-point in a BSP tree. It is used as a part of the shader for the "hint" texture. Generally speaking, any opaque texture not marked as "detail" is, by default, structural, so you shouldn't need to specify this.

Tells Q3Map2 that pre-computed visibility should not be blocked by this surface. Generally, any shaders that have blendfunc's should be marked as surfaceparm trans.

Assigns to the texture the game properties for water. This affects both the surface and the content of a brush.

This directive creates a shader name in memory, but in the editor, it displays the TGA art image specified in qer_editorImage (in the shader below this is, textures/eerie/lavahell.tga).

The editor maps a texture using the size attributes of the TGA file used for the editor image. When that editor image represents a shader, any texture used in any of the shader stages will be scaled up or down to the dimensions of the editor image. If a 128x128 pixel image is used to represent the shader in the editor, then a 256x256 image used in a later stage will be shrunk to fit. A 64x64 image would be stretched to fit. Be sure to check this on bouncy, acceleration, and power-up pads placed on surfaces other than 256 x 256. Use tcMod scale to change the size of the stretched texture. Remember that tcMod scale 0.5 0.5 will double your image, while tcMod scale 2 2 will halve it.

textures/liquids/lavahell2                      //path and name of new texture
{
        qer_editorImage textures/eerie/lavahell.tga     //based on this
        qer_nocarve                     //cannot be cut by CSG subtract
        surfaceparm noimpact                    //projectiles do not hit it
        surfaceparm lava                        //has the game properties of lava
        surfaceparm nolightmap          //environment lighting does not affect
        q3map_surfacelight 3000         //light is emitted
        tessSize 256                    //relatively large triangles
        cull disable                            //no sides are removed
        deformVertexes wave 100 sin 5 5 .5 0.02
        fogparms 0.8519142 0.309723 0.0 128 128
        {
                map textures/eerie/lavahell.tga  //base texture artwork
                tcMod turb .25 0.2 1 0.02       //texture is subjected to turbulence
                tcMod scroll 0.1 0.1            //the turbulence is scrolled
        }
}

Design Notes:

The base_light and gothic_light shaders contain numerous uses of this. It can be very useful for making different light styles (mostly to change the light brightness) without having to create a new piece of TGA art for each new shader.

A brush marked with this instruction will not be affected by CSG subtract functions. It is especially useful for water and fog textures.

This directive defines the percentage of transparency that a brush will have when seen in the editor (no effect on game rendering at all). It can have a positive value between 0 and 1. The higher the value, the less transparent the texture. Example: qer_trans 0.2 means the brush is 20% opaque and nearly invisible.

Design Notes:

On GtkRadiant 1.4 and earlier, if the shader uses qer_trans and a qer_editorImage with an alpha channel, the transparent areas of the editorImage will be 100% transparent. To keep the solid areas of the editorImage opaque, use a near 1 value for qer_trans (eg. 0.9999). This is useful for grates, windows, fences, etc. If using GtkRadiant 1.5 or later, use qer_alphaFunc for editorImage masking instead.

This directive is only supported by GtkRadiant 1.5 based editors. This is used when you have an alpha channel in the editorImage that you want to appear as an alpha mask in the editor. qer_alphaFunc by itself does not get filtered with qer_trans. This is useful for grates, windows, fences, etc.

I'm not sure if other functions and values are supported, but it seems as if it only really uses a single function/value, qer_alphaFunc gequal 0.5.

map texturename

Specifies the source texture map (a 24 or 32-bit TGA or JPG file) used for this stage. The texture may or may not contain alpha channel information. The special keywords $lightmap and $whiteimage may be substituted in lieu of an actual texture map name. In those cases, the texture named in the first line of the shader becomes the texture that supplies the light mapping data for the process. The texture name should always end with the ".tga" suffix regardless of whether the source texture map is actually a .tga file or .jpg.

map $lightmap

This is the overall lightmap for the game world. It is calculated during the Q3Map2 process. It is the initial color data found in the framebuffer. Note: due to the use of overbright bits in light calculation, the keyword rgbGen identity must accompany all $lightmap instructions.

map $whiteimage

This is used for specular lighting on MD3 models. This is a white image generated internally by the game. This image can be used in lieu of $lightmap or an actual texture map if, for example, you wish for the vertex colors to come through unaltered.

clampMap texturename

obsidian: clampMap may have been once named clampTexCoords. Changed all instances of clampTexCoords (2nd paragraph) to clampMap

Dictates that this stage should clamp texture coordinates instead of wrapping them. During a stretch function, the area, which the texture must cover during a wave cycle, enlarges and decreases. Instead of repeating a texture multiple times during enlargement (or seeing only a portion of the texture during shrinking) the texture dimensions increase or contract accordingly. This is only relevant when using something like deformTexCoordParms to stretch/compress texture coordinates for a specific special effect. Remember that the Quake III Arena engine normalizes all texture coordinates (regardless of actual texture size) into a scale of 0.0 to 1.0.

When using clampMap make sure the texture is properly aligned on the brush. The clampMap function keeps the image from tiling. However, the editor doesn't represent this properly and shows a tiled image. Therefore, what appears to be the correct position may be offset. This is very apparent on anything with a tcMod rotate and clampMap function.

Avoiding Distortion: When seen at a given distance (which can vary, depending on hardware and the size of the texture), the compression phase of a stretch function will cause a "cross"-like visual artifact to form on the modified texture due to the way that textures are reduced. This occurs because the texture undergoing modification lacks sufficient "empty space" around the displayed (non-black) part of the texture (see below, left). To compensate for this, make the non-zero portion of the texture substantially smaller (50% of maximum stretched size -- see below, right) than the dimensions of the texture. Then, write a scaling function (tcMod scale) into the appropriate shader phase, to enlarge the image to the desired proportion.

The shaders for the bouncy pads (in the sfx.shader file) show the stretch function in use, including the scaling of the stretched texture:

textures/sfx/metalbridge06_bounce
{
        //q3map_surfacelight 2000
        surfaceparm nodamage
        q3map_lightimage textures/sfx/jumppadsmall.tga
        q3map_surfacelight 400
        {
                map textures/sfx/metalbridge06_bounce.tga
                rgbGen identity
        }
        {
                map $lightmap
                rgbGen identity
                blendfunc gl_dst_color gl_zero
        }
        {
                map textures/sfx/bouncepad01b_layer1.tga
                blendfunc gl_one gl_one
                rgbGen wave sin .5 .5 0 1.5
        }
        {
                clampmap textures/sfx/jumppadsmall.tga
                blendfunc gl_one gl_one
                tcMod stretch sin 1.2 .8 0 1.5
                rgbGen wave square .5 .5 .25 1.5
        }
        // END
}

animMap frequency texture1... texture8

The surfaces in the game can be animated by displaying a sequence of 1 to 8 frames (separate texture maps). These animations are affected by other keyword effects in the same and later shader stages.

frequency

The number of times that the animation cycle will repeat within a one second time period. The larger the value, the more repeats within a second. Animations that should last for more than a second need to be expressed as decimal values.

texture1... texture8

the texture path/texture name for each animation frame must be explicitly listed. Up to eight frames (eight separate .tga files) can be used to make an animated sequence. Each frame is displayed for an equal subdivision of the frequency value.

Example:

animMap 0.25 textures/sfx/b_flame1.tga textures/sfx/b_flame2.tga textures/sfx/b_flame3.tga textures/sfx/b_flame4.tga would be a 4 frame animated sequence, calling each frame in sequence over a cycle length of 4 seconds. Each frame would be displayed for 1 second before the next one is displayed. The cycle repeats after the last frame in sequence shown.

textures/sfx/flameanim_blue
{

        //  ***********************************************
        //  *    Blue Flame                               *
        //  *    July 20, 1999 Surface Light 1800         *
        //  *    Please Comment Changes                   *
        //  ***********************************************
        qer_editorimage textures/sfx/b_flame7.tga
        q3map_lightimage textures/sfx/b_flame7.tga
        surfaceparm trans
        surfaceparm nomarks
        surfaceparm nolightmap
        cull none
        q3map_surfacelight 1800
        // texture changed to blue flame.... PAJ
        {
                animMap 10 textures/sfx/b_flame1.tga textures/sfx/b_flame2.tga
                        textures/sfx/b_flame3.tga textures/sfx/b_flame4.tga
                        textures/sfx/b_flame5.tga textures/sfx/b_flame6.tga
                        textures/sfx/b_flame7.tga textures/sfx/b_flame8.tga
                blendFunc GL_ONE GL_ONE
                rgbGen wave inverseSawtooth 0 1 0 10
        }
        {
                animMap 10 textures/sfx/b_flame2.tga textures/sfx/b_flame3.tga
                        textures/sfx/b_flame4.tga textures/sfx/b_flame5.tga
                        textures/sfx/b_flame6.tga textures/sfx/b_flame7.tga
                        textures/sfx/b_flame8.tga textures/sfx/b_flame1.tga
                blendFunc GL_ONE GL_ONE
                rgbGen wave sawtooth 0 1 0 10
        }
        {
                map textures/sfx/b_flameball.tga
                blendFunc GL_ONE GL_ONE
                rgbGen wave sin .6 .2 0 .6
        }
}

Design Notes:

To make a texture image appear for an unequal (longer) amount of time (compared to other frames), repeat that frame more than once in the sequence.

videoMap videoname

Surfaces marked with a shader containing this directive in one of its stages will display an animated video playing in a continuous loop. The video clip must be in ROQ format and playing at 30 frames per second. The ROQ file is stored in the "video" directory within the main mod directory. A third-party program is required to convert other video formats to the ROQ format for use within Quake III engine games.

textures/obsidian_video/intro
{
        qer_editorImage textures/obsidian_video/qer_intro.tga
        surfaceparm nolightmap
        {
                videoMap obsidian_intro.roq
                rgbGen identity
        }
}

Historical Information:

The ROQ format is a proprietary video format developed by Graeme Devine originally used for "The 7th Guest" for the purpose of being able to decompress quickly while maintaining high image quality. It was later adopted by Id Software for use in Quake III Arena.

Blend functions are the keyword commands that tell the Quake III Arena graphic engine's renderer how graphic layers are to be mixed together.

Simplified Blend Functions

The most common blend functions are set up here as simple commands, and should be used unless you really know what you are doing.

add

Shorthand command for blendFunc gl_one gl_one. Effects like fire and energy are additive.

filter

Shorthand command that can be substituted for either blendFunc gl_dst_color gl_zero or blendFunc gl_zero gl_src_color. A filter will always result in darker pixels than what is behind it, but it can also remove color selectively. Lightmaps are filters.

blend

Shorthand command for blendFunc gl_src_alpha gl_one_minus_src_alpha. This is conventional transparency, where part of the background is mixed with part of the texture.

Explicit Blend Functions

Getting a handle on this concept is absolutely key to understanding all shader manipulation of graphics.

blendFunc or "Blend Function" is the equation at the core of processing shader graphics. The formula reads as follows:

[source * (srcBlend)] + [destination * (dstBlend)]

Source is usually the RGB color data in a texture TGA file (remember it's all numbers) modified by any rgbGen and alphaGen. In the shader, the source is generally identified by command map, followed by the name of the image.

Destination is the color data currently existing in the frame buffer.

Rather than think of the entire texture as a whole, it maybe easier to think of the number values that correspond to a single pixel, because that is essentially what the computer is processing... one pixel of the bitmap at a time.

The process for calculating the final look of a texture in place in the game world begins with the precalculated lightmap for the area where the texture will be located. This data is in the frame buffer. That is to say, it is the initial data in the destination. In an unmanipulated texture (i.e. one without a special shader script), color information from the texture is combined with the lightmap. In a shader-modified texture, the $lightmap stage must be present for the lightmap to be included in the calculation of the final texture appearance.

Each pass or "stage" of blending is combined (in a cumulative manner) with the color data passed onto it by the previous stage. How that data combines together depends on the values chosen for the source blends and destination blends at each stage. Remember it's numbers that are being mathematically combined together that are ultimately interpreted as colors.

A general rule is that any source blend other than GL_ONE (or GL_SRC_ALPHA where the alpha channel is entirely white) will cause the source to become darker.

Source Blend (srcBlend)

The following values are valid for the source blend part of the equation.

GL_ONE

This is the value 1. When multiplied by the source, the value stays the same. The value of the color information does not change.

GL_ZERO

This is the value 0. When multiplied by the source, all RGB data in the source becomes zero (essentially black).

GL_DST_COLOR

This is the value of color data currently in the destination (frame buffer). The value of that information depends on the information supplied by previous stages.

GL_ONE_MINUS_DST_COLOR

This is nearly the same as GL_DST_COLOR except that the value for each component color is inverted by subtracting it from one. (i.e. R = 1.0 - DST.R, G = 1.0 - DST.G, B = 1.0 - DST.B, etc.)

GL_SRC_ALPHA

The TGA file being used for the source data must have an alpha channel in addition to its RGB channels (for a total of four channels). The alpha channel is an 8-bit black and white only channel. An entirely white alpha channel will not darken the source.

GL_ONE_MINUS_SRC_ALPHA

This is the same as GL_SRC_ALPHA except that the value in the alpha channel is inverted by subtracting it from one. (i.e. A=1.0 - SRC.A)

Destination Blend (dstBlend)

The following values are valid for the destination blend part of the equation.

GL_ONE

This is the value 1. When multiplied by the destination, the value stays the same the value of the color information does not change.

GL_ZERO

This is the value 0. When multiplied by the destination, all RGB data in the destination becomes zero (essentially black).

GL_SRC_COLOR

This is the value of color data currently in the source (which is the texture being manipulated here).

GL_ONE_MINUS_SRC_COLOR

This is the value of color data currently in source, but subtracted from one (i.e. inverted).

GL_SRC_ALPHA

The TGA file being used for the source data must have an alpha channel in addition to its RGB channels (for a total of four channels). The alpha channel is an 8-bit black and white only channel. An entirely white alpha channel will not darken the source.

GL_ONE_MINUS_SRC_ALPHA

This is the same as GL_SRC_ALPHA except that the value in the alpha channel is inverted by subtracting it from one. (i.e. A=1.0 - SRC.A).

Doing the Math: The Final Result

The product of the source side of the equation is added to the product of the destination side of the equation. The sum is then placed into the frame buffer to become the destination information for the next stage. Ultimately, the equation creates a modified color value that is used by other functions to define what happens in the texture when it is displayed in the game world.

Default Blend Function

If no blendFunc is specified then no blending will take place. A warning is generated if any stage after the first stage does not have a blendFunc specified.

Technical Information/Limitations Regarding Blend Modes:

The Riva 128 graphics card supports ONLY the following blendmodes:

• GL_ONE, GL_ONE
• GL_DST_COLOR, GL_ZERO
• GL_ZERO, GL_SRC_COLOR
• GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA
• GL_ONE_MINUS_SRC_ALPHA, GL_SRC_ALPHA

Cards running in 16 bit color cannot use any GL_DST_ALPHA blends.

There are two color sources for any given shader, the texture file and the vertex colors. Output at any given time will be equal to TEXTURE multiplied by VERTEXCOLOR. Most of the time VERTEXCOLOR will default to white (which is a normalized value of 1.0), so output will be TEXTURE (this usually lands in the Source side of the shader equation). Sometimes you do the opposite and use TEXTURE = WHITE, but this is only commonly used when doing specular lighting on entities (i.e. shaders that level designers will probably never create.

The most common reason to use rgbGen is to pulsate something. This means that the VERTEXCOLOR will oscillate between two values, and that value will be multiplied (darkening) the texture.

If no rgbGen is specified, either "identityLighting" or "identity" will be selected, depending on which blend modes are used.

rgbGen identity

Colors are assumed to be all white (1.0, 1.0, 1.0). All filters stages (lightmaps, etc) will get this by default.

rgbGen identityLighting

Colors will be (1.0, 1.0, 1.0) if running without overbright bits (NT, Linux, windowed modes), or (0.5, 0.5, 0.5) if running with overbright. Overbright allows a greater color range at the expense of a loss of precision. Additive and blended stages will get this by default.

rgbGen vertex

Colors are filled in directly by the data from the map or model files. User rgbGen vertex + alphaGen const or rgbGen exactVertex to disable surfaces from being affected by alphaMod volumes.

Design Notes:

rgbGen vertex should be used when you want the RGB values to be computed for a static model (i.e. mapobject) in the world using precomputed static lighting from Q3BSP. This would be used on things like the gargoyles, the portal frame, skulls, and other decorative models put into the Quake III Arena world.

rgbGen oneMinusVertex

As rgbGen vertex, but inverted. This keyword would probably not be used by a level designer.

rgbGen exactVertex

Like vertex, except exactVertex ignores overbrightbits. Generally brighter under default settings.

rgbGen fromVertex

(Pending)

rgbGen entity

Colors are grabbed from the entity's modulate field. This is used for things like explosions. This keyword would probably not be used by a level designer.

rgbGen oneMinusEntity

As rgbGen entity, but inverted.

rgbGen lightingDiffuse

Colors are computed using a standard diffuse lighting equation. It uses the vertex normals to illuminate the object correctly.

Design Notes:

rgbGen lightingDiffuse is used when you want the RGB values to be computed for a dynamic model (i.e. non-map object) in the world using regular in-game lighting. For example, you would specify on shaders for items, characters, weapons, etc.

rgbGen noise

(Probably doesn't exist)

rgbGen wave func base amplitude phase freq

Colors are generated using the specified waveform. An affected texture with become darker and lighter, but will not change hue. Hue stays constant. Note that the RGB values for color will not go below 0 (black) or above 1 (white). Valid waveforms are sin, triangle, square, sawtooth, inversesawtooth and noise (see Waveform Functions).

rgbGen const ( R G B )

A constant vertex colour is assigned to the affected surface. This modifies the hue of the texture.

The alpha channel can be specified like the RGB channels. If not specified, it defaults to 1.0.

alphaGen lightingSpecular

alphaGen wave

alphaGen entity

alphaGen oneMinusEntity

alphaGen vertex

alphaGen oneMinusVertex

alphaGen const N.N

A constant vertex alpha is assigned to the affected surface. This modifies the transparency of the texture.

alphaGen portal

This rendering stage keyword is used in conjunction with the surface parameter keyword portal. The function accomplishes the "fade" that causes the scene in the portal to fade from view. Specifically, it means "Generate alpha values based on the distance from the viewer to the portal." Use alphaGen portal on the last rendering pass.

Specifies how texture coordinates are generated and where they come from. Valid functions are base, lightmap, environment and vector.

base

Base texture coordinates from the original art.

lightmap

Lightmap texture coordinates.

environment

Projects a texture from environment mapping (typically used for shiny reflective surfaces like polished steel).

vector

Projects a texture from a specified direction.

tcGen vector ( sx sy sz ) ( tx ty tz )

New texture coordinate generation by world projection. This allows you to project a texture onto a surface in a fixed way, regardless of its orientation.

S-coordinates correspond to the "x" coordinates on the texture itself. T-coordinates correspond to the "y" coordinates on the texture itself. The measurements are in game units.

Example:

tcGen vector ( 0.01 0 0 ) ( 0 0.01 0 )

This would project a texture with a repeat every 100 units across the X/Y plane. The value comes from dividing the game units from 1, in this case, 1/100.

Specifies how texture coordinates are modified after they are generated. The valid functions for tcMod are rotate, scale, scroll, stretch, transform and turb. Transform is a function generally reserved for use by programmers who suggest that designers leave it alone. When using multiple tcMod functions during a stage, place the scroll command last in order, because it performs a mod operation to save precision, and that can disturb other operations. Texture coordinates are modified in the order in which tcMods are specified. In otherwords, if you see the following, the texture coordinates will be scaled, then scrolled.

tcMod scale 0.5 0.5
tcMod scroll 1 1

tcMod rotate degrees/sec

This keyword causes the texture coordinates to rotate. The value is expressed in degrees rotated each second. A positive value means clockwise rotation. A negative value means counterclockwise rotation. For example "tcMod rotate 5" would rotate texture coordinates 5 degrees each second in a clockwise direction. The texture rotates around the center point of the texture map, so you are rotating a texture with a single repetition, be careful to center it on the brush (unless off-center rotation is desired).

tcMod scale sScale tScale

Resizes (enlarges or shrinks) the texture coordinates by multiplying them against the given factors of sScale and tScale. The values "s" and "t"conform to the "x" and "y" values (respectively) as they are found in the original texture TGA. The values for sScale and tScale are NOT normalized. This means that a value greater than 1.0 will increase the size of the texture. A positive value less than one will reduce the texture to a fraction of its size and cause it to repeat within the same area as the original texture (Note: see clampTexCoords for ways to control this).

Example: tcMod scale 0.5 2 would cause the texture to repeat twice along its width, but expand to twice its height (in which case half of the texture would be seen in the same area as the original)

tcMod scroll sSpeed tSpeed

Scrolls the texture coordinates with the given speeds. The values "s" and "t" conform to the "x" and "y" values (respectively) as they are found in the original texture TGA. The scroll speed is measured in "textures" per second. A "texture" is the dimension of the texture being modified and includes any previous shader modifications to the original TGA). A negative s value would scroll the texture to the left. A negative t value would scroll the texture down.

Example: tcMod scroll 0.5 -0.5 moves the texture down and right (relative to the TGA files original coordinates) at the rate of a half texture each second of travel.

This should be the LAST tcMod in a stage. Otherwise there may be a popping or snapping visual effect in some shaders.

tcMod stretch func base amplitude phase frequency

Stretches the texture coordinates with the given function. Stretching is defined as stretching the texture coordinate away from the center of the polygon and then compressing it towards the center of the polygon. (see Chapter 1: Key Concepts for waveform parameter definitions).

tcMod transform m00 m01 m10 m11 t0 t1

Transforms each texture coordinate as follows:

S' = s * m00 + t * m10 + t0
T' = s * m01 + t * m11 + t1

This is primarily used by programmers.

tcMod turb base amplitude phase frequency

Applies turbulence to the texture coordinate. Turbulence is a back and forth churning and swirling effect on the texture.

base

Undefined

amplitude

This is essentially the intensity of the disturbance or twisting and squiggling of the texture.

phase

See the explanation for phase under the deformVertexes keyword.

frequency

Frequency. This value is expressed as repetitions or cycles of the wave per second. A value of one would cycle once per second. A value of 10 would cycle 10 times per second. A value of 0.1 would cycle once every 10 seconds.

This controls the depth comparison function used while rendering. The default is "lequal" (Less than or equal to) where any surface that is at the same depth or closer of an existing surface is drawn. This is used for textures with transparency or translucency. Under some circumstances you may wish to use "equal", e.g. for light-mapped grates that are alpha tested (it is also used for mirrors).

By default, writes to the depth buffer when depthFunc passes will happen for opaque surfaces and not for translucent surfaces. Blended surfaces can have the depth writes forced with this function.

This feature was not used in Quake III Arena maps, but still functions. Designates this stage as a detail texture stage, which means that if the c_var, r_detailtextures, is set to 0 then this stage will be ignored (detail will not be displayed). This keyword, by itself, does not affect rendering at all. If you do put in a detail texture, it has to conform to very specific rules. Specifically, the blendFunc:

blendFunc GL_DST_COLOR GL_SRC_COLOR

This is also the simple blend function: blendFunc filter

And the average intensity of the detail texture itself must be around 127.

Detail is used to blend fine pixel detail back into a base texture whose scale has been increased significantly. When detail is written into a set of stage instructions, it allows the stage to be disabled by the c_var console command setting "r_detailtextures 0".

A texture whose scale has been increased beyond a 1:1 ratio tends not to have very high frequency content. In other words, one texel can cover a lot of real estate. Frequency is also known as "detail." Lack of detail can appear acceptable if the player never has the opportunity to see the texture at close range. But seen close up, such textures look glaringly wrong within the sharp detail of the Quake III Arena environment. A detail texture solves this problem by taking a noisy "detail" pattern (a tiling texture that appears to have a great deal of surface roughness) and applying it to the base texture at a very densely packed scale (that is, reduced from its normal size). This is done programmatically in the shader, and does not require modification of the base texture. Note that if the detail texture is the same size and scale as the base texture that you may as well just add the detail directly to the base texture. The theory is that the detail texture's scale will be so high compared to the base texture (e.g.; 9 detail texels fitting into 1 base texel) that it is literally impossible to fit that detail into the base texture directly.

For this to work, the rules are as follows:

• The lightmap must be rendered first. This is because the subsequent detail texture will be modifying the lightmap in the framebuffer directly.
• The base texture must be rendered next.
• The detail texture must be rendered last since it modifies the lightmap in the framebuffer. There is a bug in Quake III that disables all stages in a shader after a "detail" stage if r_detailTextures is set to 0.
• The detail texture MUST have a mean intensity around 127-129. If it does not then it will modify the displayed texture's perceived brightness in the world.
• The detail shader stage MUST have the "detail" keyword or it will not be disabled if the user uses the "r_detailtextures 0" setting.
• The detail stage MUST use "blendFunc GL_DST_COLOR GL_SRC_COLOR". Any other BlendFunc will cause mismatches in brightness between detail and non-detail views.
• The detail stage should scale its textures by some amount (usually between 3 and 12) using "tcMod scale" to control density. This roughly corresponds to coarseness. A very large number, such as 12, will give very fine detail, however that detail will disappear VERY quickly as the viewer moves away from the wall since it will be MIP mapped away. A very small number, e.g. 3, gives diminishing returns since not enough is brought in when the user gets very close. I'm currently using values between 6 and 9.5. You should use non-integral numbers as much as possible to avoid seeing repeating patterns.
• Detail textures add one pass of overdraw, so there is a definite performance hit.
• Detail textures can be shared, so designers may wish to define only a very small handful of detail textures for common surfaces such as rocks, etc.

An example (non-existent) detail shader is as follows:

textures/bwhtest/foo
{
        q3map_globalTexture     //may be required when using tcMod scale in later stages

        // draw the lightmap first
        {
                map $lightmap
                rgbGen identity
        }

        // draw the base texture
        {
                map textures/castle/blocks11b.tga
                blendFunc filter
        }

        // highly compressed detail texture
        {
                map textures/details/detail01.tga
                blendFunc GL_DST_COLOR GL_SRC_COLOR     //MUST BE USED
                detail  //allows detail shaders to be disabled
                tcMod scale 9.1 9.2
        }
}

Determines the alpha test function used when rendering this map. Valid values are GT0, LT128, and GE128. These correspond to "GREATER THAN 0", "LESS THAN 128", and "GREATER THAN OR EQUAL TO 128". This function is used when determining if a pixel should be written to the framebuffer. For example, if GT0 is specified, the only the portions of the texture map with corresponding alpha values greater than zero will be written to the framebuffer. By default alpha testing is disabled.

Both alpha testing and normal alpha blending can be used to get textures that have see-through parts. The difference is that alphaFunc is an all-or-nothing test, while blending smoothly blends between opaque and translucent at pixel edges. Alpha test can also be used with depthWrite, allowing other effects to be conditionally layered on top of just the opaque pixels by setting depthFunc to equal.

Enables parallax/offset mapping on the surface, using the normalmap's alpha channel (heightmap) to simulate depth and surface relief without additional geometry. This can range from simple offset mapping to multi-step relief mapping, trading visual quality for performance.

type

The offset mapping technique to use. Possible values include:

• disabled — disables offset mapping for this material.
• default — uses whatever the engine's current r_glsl_offsetmapping mode is.
• linear — simple single-step offset (fastest, lowest quality).
• relief — multi-step relief/parallax occlusion mapping (slowest, highest quality; ~14–15 texture lookups).

scale

Controls the depth scale (extrusion strength) of the offset mapping effect. Higher values push the heightmap further in/out, creating a more pronounced 3D effect. This effectively scales the bumpmap displacement in game units. Typical values are in the 1–4 range; overly large values cause visual artifacts at grazing angles.

Bias parameters (optional)

The optional third and fourth parameters control the null point (base level) of the heightmap — i.e., which pixel brightness value in the heightmap is considered "flush" with the surface, with values above it being raised and values below being recessed.

bias <biasvalue>

Sets a custom null point directly as a normalized float (0.0–1.0). A value of 0.5 (equivalent to 128 in 8-bit) makes gray the base level: black becomes a positive offset (raised), white becomes a negative offset (recessed). Without this parameter, the default null point is at white (1.0), meaning white has no offset and darker values push outward.

match <value>

Sets the null point using a normalized float pixel value (0.0–1.0) that represents the "flush with surface" brightness in the heightmap.

match8 <value>

Sets the null point using an 8-bit pixel value (0–255). For example, match8 148 means that pixels with brightness 148 out of 255 are considered flush with the surface. Pixels darker than 148 will be offset in one direction, and pixels brighter than 148 will be offset in the other.

match16 <value>

Sets the null point using a 16-bit pixel value (0–65535), for use with higher-precision heightmaps.

Design Notes

The bias/match parameter is critical for getting correct-looking offset mapping. If your heightmap is authored so that mid-gray (128) represents the flat surface, use match8 128 or bias 0.5. If you leave the bias at default (white = base), dark areas will appear to extrude outward and white areas will sit flat, which may or may not be the desired effect.

Offset mapping adds extra texture lookups per light pass: simple offset mapping uses ~3 lookups, while relief mapping uses ~14–15. Use sparingly on surfaces that are lit by many realtime lights.

Example usage:

dpOffsetMapping linear 2
dpOffsetMapping relief 3 bias 0.5
dpOffsetMapping default 1 match8 148

Enables self-shadowing offset mapping on the surface. This is an extension of dpOffsetMapping that additionally computes shadows cast by the heightmap onto itself, giving a much more convincing sense of depth on surfaces with pronounced relief (e.g., brickwork, cobblestones, rocky terrain).

scale

Controls the self-shadowing intensity/depth. Higher values produce deeper, more pronounced self-shadows.

offsetscale

The offset mapping depth scale, equivalent to the scale parameter in dpOffsetMapping. Controls how far the heightmap displaces the surface texture.

Bias parameters (optional)

The optional offsetbiastype and offsetbiasvalue parameters work identically to the bias parameters in dpOffsetMapping:

bias <value>

Normalized float (0.0–1.0) null point.

match <value>

Normalized float pixel value as null point.

match8 <value>

8-bit pixel value (0–255) as null point.

match16 <value>

16-bit pixel value (0–65535) as null point.

Design Notes

Self-shadowing is significantly more expensive than standard offset mapping, as it requires additional ray-march steps against the heightmap to determine shadow visibility. Use it on key surfaces where the visual payoff justifies the cost (feature walls, close-up hero textures), not on every surface in the map.

Example usage:

dpSelfShadowing 1.5 2 match8 128

Disables fog rendering for the surface.

Offsets surface depth to avoid z-fighting; useful for decals. Parameters optional; defaults factor=0, offset=-2.

Changes software sorting behavior for blended materials.

• distance: default distance sorting
• hud: always on top of other blended materials
• sky: always behind other blended materials

Forces material to be a shadow caster even if blended or not drawn (blended surfaces normally don’t cast shadows).

Useful for invisible/lowpoly shadow meshes.

Disables shadow casting for the material.

Disables realtime lighting on the surface.

Multiplies gloss intensity (default 1.0; 0.5 halves; 2.0 doubles). Applied on top of base gloss from the texture’s _gloss color.

Scales gloss exponent (sharpness). Multiplies the exponent stored in _gloss alpha (or forces base exponent to 1 if no alpha).

Typical values: 0.25 (wood), 2.0 (glass).

Adds ambient light to smooth shading on rough/lowpoly surfaces (e.g., grass) to reduce artefacts.

Makes material reflective; reflection alpha-blended and color-modulated. Distortion works with normalmap to simulate nonplanar water.

Important: expensive (“hard” shader) and can slow rendering if overused.

Adds refraction; replaces texture transparency. Distortion works with normalmap to simulate nonplanar water.

Adds a combined water shader (reflection + refraction mixed via Fresnel; layered below texture).

Example: dpwater 0.4 1.0 0.3 1.0 0.28 0.21 0.18 0.80 0.76 0.65 0.0

Animates water normalmap by duplicating, scrolling, offsetting, and multiplying layers.

Tip: globalScale affects speed.

Flags surface as a camera surface for portal-like effects.

Sets a static cubemap texture for reflections.

Important: requires a _reflect skinframe texture to set local reflection intensity.

Example: dpreflectcube textures/environment/reflect1

Disables (“kills”) the shader’s visual stages if the given cvar matches a condition.

Operators: ==, !=, >, >=, <, <=.

Example: dpshaderkillifcvar r_foo == 42

Prevents killing; has priority over dpShaderKillIfCvar.

Kills material if the cvar’s float value is 0.

Opposite of dpShaderKillIfCvarZero (prevents kill when cvar is zero).

Uses the surface's draw geometry for collision instead of generated BSP collision (useful for models without it). Requires BIH enabled.

Disables BIH construction for the surface; optimization for surfaces that don’t need physics (e.g., grass).