Darkplaces material system/General Keywords

surfaceparm
This is, by the fact, most widely used and most tricky material keyword.

All surfaceparm keywords are preceded by the word surfaceparm as follows: surfaceparm nonsolid or surfaceparm trans. Each surfaceparm have corresponding q3map_surfaceparmname keyword (q3map_nonsolid, q3map_trans etc.) which is only acquired by Q3map2. Surfaceparm keywords change the physical nature of the materials and the brushes. Changing any of these values will likely require the map to be re-compiled. These are global and affect the entire shader.

This document skips all Q3map2 surfaceparms that is not used by Blood Omnicide.

General surfaceparms
surfaceparm alphashadow
 * This keyword applied to a side 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.
 * Used by Q3map2 light phase.

surfaceparm detail
 * This surface attribute causes a brush to be ignored by the Q3Map2 process for generating possible break-points in the BSP tree. It functionality is same as marking brush as detail in level editor.
 * Used by Q3map2 BSP phase

surfaceparm lava
 * Assigns to the material the game properties set for lava. This affects contents of the brush.
 * Used by engine (BIH collision) and q3map2 (bsp phase).

surfaceparm lightfilter
 * 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.
 * Used by Q3map2 light phase.

surfaceparm nodraw
 * Prevents Q3map2 from generating drawsurfaces for this material.
 * Used by Q3map2 BSP phase.

surfaceparm nomarks
 * Prevents engine from spawning decals for this surface.
 * Used by engine renderer.

surfaceparm nolightmap
 * This surface will have no lightmap generated. This will save some memory and make map compilation faster.
 * Used by Q3map2 light phase.

surfaceparm nonsolid
 * Surface does not block the movement of entities in the game world. This affects the content of a brush. This still make q3map2 generate collision surfaces.
 * Used by engine (BIH collision) and q3map2 (bsp phase).

surfaceparm slime
 * Assigns to the material the game properties set for slime. In Blood Omnicide, slime is a swamp.
 * Used by engine (BIH collision) and q3map2 (bsp phase).

surfaceparm trans
 * Tells Q3Map2 that pre-computed visibility should not be blocked by this surface.
 * Used by q3map2 BSP phase.

surfaceparm water
 * Assigns to the material the game properties set for water. This affects both the surface and the content of a brush.
 * Used by engine (BIH collision) and q3map2 (bsp phase).

System surfaceparms
This is surfaceparms is only used in common materials. You dont need to specify them on your new materials.

surfaceparm hint
 * 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.
 * Used by Q3map2 BSP phase. This keyword is used on common/hint material.

surfaceparm monsterclip
 * Surface with this flag will block NPC movement. Should be used with surfaceparm nonsolid.
 * Used by engine (collision). This keyword is used on common/monsterclip material. You dont need to specify it on your new materials.

surfaceparm lightgrid
 * The min/max bounds of brushes with this material in a map will define the bounds of the map's Lightgrid.
 * Used by Q3map2 light phase. This keyword is used on common/lightgrid material. You dont need to specify it on your new materials.

surfaceparm playerclip
 * Surface with this flag will block player movement. Should be used with surfaceparm nonsolid.
 * Used by engine (collision). This keyword is used on common/playerclip material.

surfaceparm origin
 * 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.
 * Used by q3map2 BSP phase. This keyword is used on common/origin material

surfaceparm structural
 * 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 common/hint material. Generally speaking, any opaque material not marked as "detail" is, by default, structural, so you shouldn't need to specify this.
 * Used by q3map2 BSP phase.

Custom surfaceparms
This surface parameters are defined by custinfoparms.txt and used to assign a game-related properties to material, such as hit effect and step sound.

Blood Omnicide have this game-physics materials:


 * grass
 * ice
 * dirt
 * wood
 * oldwood
 * ground
 * sand
 * dullmetal
 * brookwater
 * glass
 * fur
 * marble
 * hay
 * slate
 * flesh
 * metal
 * oldmetal
 * stone
 * oldstone
 * plan

cull none
Every surface of a polygon has two sides, a front and a back. Typically, we only see the front side. For example, a solid block you only show the front side. In some situations we see both (grates, screens etc.).

To "cull" means to remove. This keyword allows to disable side culling, so both sides of the surfaces would be visible.

noPicMip
This causes the texture to ignore r_picmip cvar. The image will always be high resolution. Applicate to a small low-resolution textures that will be overblurred with r_picmip. Not used in Blood Omnicide.

noMipMaps
Implies noPicMip. Also prevents the generation of any lower resolution mipmaps for use by the 3D card. This saves 25% of memory used to store this texture (both RAM and VRAM).

deformVertexes
This function performs a general deformation on the surface's vertexes, changing the actual shape of the surface before drawing the material. You can stack multiple deformVertexes commands to modify positions in more complex ways, making an object move in two dimensions, for instance.

deformVertexes

 * Designed for water surfaces, modifying the values differently at each point. It accepts the standard waveform functions.
 * The "div" parameter is used to control the wave "spread" - a value equal to the tesselation distance (see q3map_tessSize, a subdivision size, in game units, used for the material when seen in the game world).

deformVertexes normal  

 * This deformation affects the normals of a vertex without actually moving it, which will effect later material options like lighting (especially specular) and environment mapping (see stage specific keywords for tcGen environment). If the materialdon't use normals in any of their calculations, there will be no visible effect.


 * IMPORTANT NOTE: In Darkplaces, offset mapping uses vertex normals for the calculations. deformVertexes normal most likely will mess it up.
 * Design Notes: Putting values of 0.1 t o 0.5 in Amplitude and 1.0 to 4.0 in the Frequency can produce some satisfying results.

deformVertexes bulge   

 * This forces a bulge to move along the given S and T directions. Designed for use on curved pipes.

deformVertexes move   

 * This keyword is used to make a brush, curve patch or model appear to move together as a unit. The   and  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 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.

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 an .md3 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.

Specific parameter definitions for deform keywords
div
 * This is roughly defined as the size of the waves that occur. It is measured in game units. Smaller values create a greater density of smaller wave forms occurring in a given area. Larger values create a lesser density of waves, or otherwise put, the appearance of larger waves. To look correct this value should closely correspond to the value (in pixels) set for tessSize (tessellation size) of the texture. A value of 100.0 is a good default value (which means your tessSize should be close to that for things to look "wavelike").

func
 * This is the type of wave form being created. Sin stands for sine wave, a regular smoothly flowing wave. Triangle is a wave with a sharp ascent and a sharp decay. It will make a choppy looking wave forms. A square wave is simply on or off for the period of the frequency with no in between. The sawtooth wave has the ascent of a triangle wave, but has the decay cut off sharply like a square wave. An inversesawtooth wave reverses this.

base
 * This is the distance, in game units that the apparent surface of the texture is displaced from the actual surface of the brush as placed in the editor. A positive value appears above the brush surface. A negative value appears below the brush surface. An example of this is the Quad effect, which essentially is a shell with a positive base value to stand it away from the model surface and a 0 (zero) value for amplitude.

amplitude
 * The distance that the deformation moves away from the base value. See Wave Forms in the introduction for a description of amplitude.

phase
 * See Wave Forms in the introduction for a description of phase.

frequency
 * See Wave Forms in the introduction for a description of frequency.

dpMeshCollisions
Use surface's draw geometry for collision detection instead of generated BSP geometry (some models have no one). This works only if BIH is enabled.

dpPolygonOffset &lt;factor&gt; &lt;offset&gt;
Allows arbitrary offsets of a surface's depth during rendering. Material with this keyword are able to stack over rest of geometry with no z-fighting. Useful for decals.

Both parameters are optional, if not used, a default factor of 0 and offset -2 is used.

dpTransparentSort
Rendering of blended materials requires software sorting to keep the depth order of geometry. This keyword changes default distance sorting to allow for special effects.
 * distance : default distance-based sorting
 * hud : this surface will always be ontop of all another blended materials
 * sky : opposite to hud, this surface will always ve vehing all other blender materials.

Per-Pixel Lightning
This keywords controls various parameters used by per-pixel lighting of a surface.

dpShadow
Forces this material to be shadow caster even if it's blended or not drawn (blended surfaces by default is not casting shadows).

dpNoShadow
Discards material from shadow casting.

dpNoRtlight
Disables any realtime lighting on a surface.

dpGlossIntensityMod
Multiplies gloss intensity of this material. Default value is 1; 0.5 will halve gloss effect intensity, 2.0 will double it etc. This are used ontop on base gloss intensity set by a texture's _gloss color.

dpGlossExponentMod
Scales gloss exponent for a surface. Gloss exponent controls how sharp gloss effect is. Low values will make surface matte, higher values will make it look like a covered by a plastic film. Just like intensity mod, this is a multiplier to a value in texture's _gloss alpha (if there is no alpha - base gloss exponent is forced to be 1).

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

dpRtlightAmbient
Smooths out shading of a surface by adding amount of ambient light. This is useful on very grude and lowpoly surfaces (such as grass) because strong shading will show artefacts caused by low detalisation of a mesh.

Reflection and refraction
This material keywords allows to add refraction and reflection effects to a surface. All reflective and refractive effects are part of water shader, so they are only visible when r_water cvar is 1.

dpReflect    
Make this material reflective. The reflection is alpha blended on the texture with the given alpha, and modulated by the given color. Distort is used in conjunction with the normalmap to simulate a nonplanar water surface.

dpRefract  <g> <b>
Works pretty same as reflection and can be combined with it (though it's not good). The refraction replaces the transparency of the texture. Distort is used in conjunction with the normalmap to simulate a nonplanar water surface.

dpWater    <refractR> <refractG> <refractB>  <reflectR> <reflectG> <reflectB>
Add a water shader to a material. This combines the effects of dpreflect and dprefract to simulate a water surface. However, the refraction and the reflection are mixed using a Fresnel equation that makes the amount of reflection slide from reflectmin when looking parallel to the water to reflectmax when looking directly into the water. The result of this reflection/refraction mix is then layered BELOW the texture of the shader, so basically, it "fills up" the alpha values of the water. The alpha value is a multiplicator for the alpha value on the texture (set this to a small value like 0.1) to emphasize the reflection and make the water transparent; but if r_water is 0, alpha isn't used, so the water can be very visible then too.

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

dpWaterScroll <speedScale> <globalScale>
Animate surface normalmap in water shader by duplicating it, scrolling, offsetting and multiplying the layers.

dpCamera
Flags this surface as camera surface. Used to make portal effects like ones seen in Pray. Not used in Blood Omnicide.

dpReflectCube
Sets static cubemap texture for reflections.

Typical usage:

dpreflectcube textures/environment/reflect1

Shader Kill
This keywords are used to hide this material (as if it has no stages) under certain circumstances. Only affects visual appearance of material, not collisions or contents.

dpShaderKillIfCvar
Kills this material is cvar matches a value. // kill this shader if r_foo is 42 dpshaderkillifcvar r_foo == 42 Operators are:
 * == - equal
 * != - not equal
 * > - greater
 * >= - greater or equal
 * < - lesser
 * <= - lesser or equal

dpNoShaderKillIfCvar
Prevents material from being killed. Have a priority over dpshaderkillifcvar.

dpShaderKillIfCvarZero
Kills material is supplied cvar's float value is 0.

dpNoShaderKillIfCvarZero
Opposite to above.