Making DOOM 3 Mods : Tables & Materials

Material decls are similar to shader files from Quake3, but they are a lot more powerful. Materials have a lot of power, especially when combined with scripts and GL programs.

In Quake3, you could do all kinds of neat things with sin waves, saw tooth waves, square waves and other types of waves, but you were pretty much screwed if you wanted any kind of non standard wave form. In Doom 3, you can define arbitrary data lookup tables, then reference them in your materials.

The format of a table definiton is:

table <tablename> { [snap] [clamp] { <data>, <data>, ... } }
Where [snap] is an optional key word which means "jump directly from one value to the other (don't blend between values)" and [clamp] is an optional key word which means "don't wrap around if the index is outside the range of table elements, (return the first value if less or the last value if it's more)". Both keywords are optional, and can be used together.

Now, armed with this knowledge, we can easily construct a square wave lookup table:

table squarewave { snap { 0, 1 } }
The sin table is a bit harder, but lucky for you, it's already defined
Every material file has a global section, followed by one or more stages. The global section, as the name implies, sets properties that affect all the stages. In Quake3 the stages were pretty easy to understand because the engine rendered them in order: stage 1, then stage 2, then stage 3, etc.. In Doom 3 the order is not quite as simple because of the way the lighting system works, but for the most part, they are still rendered in order.

Let's look at a simple material (some random wall in the alpha labs):

    qer_editorimage textures/alphalabs/a_lfwall21b
    bumpmap         textures/base_wall/lfwall21_local
    diffusemap      textures/alphalabs/a_lfwall21b
    specularmap     textures/alphalabs/a_lfwall21b_s

The first line is the name of the material (which in this case also happens to be the name of the diffuse map). Notice the absence of a 'material' keyword. This is because it is in a .mtr file, where the 'material' keyword is assumed. If you chose to put this in another type of file, you would need the 'material' keyword.

The global section begins right after the open curly brace. The first key word we see is qer_editorimage, which tells Radiant which image to use in the editor. This is the image used in the texture window, as well as in the 3D view. Next we define the bump map (normal map), the diffuse map (colors), and the specular map (gloss). This is about as basic of a material file you can get, while still using the advanced lighting features. Technically all you need is 'diffusemap', in which case the specular map is black, the bump map is blue, and the editorimage is the diffusemap. Creating an entire map with those types of materials will look roughly like Quake 3.

This material looks like it doesn't have any stages, but in fact it has 3 stages. The 'bumpmap' 'diffusemap' and 'specularmap' keywords are simply shortcuts for stages as we will see later.

Shaders in Materials
Doom 3 has the ability to use custom GL vertex and fragment programs when rendering a stage of a material. This is mostly seen in the 'heat haze' effects around fire, in the warping effects on glass, and in the warping effects on various projectiles (like the BFG). For documentation on how to write your own vertex and fragment programs, take a look at these two documents: Vertex Programs, Fragment Programs. There is nothing stopping an artist from writing those, but I would really let a programmer handle writing the GL program. The main thing an artist or level designer needs to know is how to use the GL program in their materials.

This is the material file for outdoor glass, which is one of the more complex materials in the game:

    sort decal

    qer_editorimage textures/glass/glass1
        vertexProgram heatHaze.vfp
        vertexParm  0  0 , 0  // texture scrolling
        vertexParm  1  .5  // magnitude of the distortion

        fragmentProgram heatHaze.vfp
        fragmentMap 0  _currentRender
        fragmentMap 1  textures/sfx/vp1 // the normal map for distortion
        map makealpha(textures/glass/glass1)
        blend gl_dst_alpha, gl_one
        cubeMap env/gen2
        red     Parm0
        green   Parm1
        blue    Parm2
        texgen  reflect
        blend filter
        map textures/glass/outdoor_glass1fx

First the global section sets up some properties for the material. Two keywords to take note of: 'glass' specifies the sound that is made when things hit it (NOT the way it looks). The 'forceoverlays' keyword forces decals like blood to draw on it. Normally blood and weapon decals are disabled on transparent surfaces because it tends to look wrong.

The first stage in this material is what sets up the vertex and pixel program. The programs are defined in "glprogs/heatHaze.vfp". This stage is completely skipped on older (non ARB2) hardware, and is actually drawn last on modern hardware because of the reference to _currentRender. As the comments explain, for this particular vertex program, parm 0 defines the texture scrolling, and parm 1 defines how much the image is distorted. The meaning of these parms depends completely on how the vertex program is written, so consult your programmer.

The second stage sets up an alpha channel stage. It doesn't actually write anything to the screen, but rather it sets some values in the alpha channel which are used in the next stage.

The third stage is the main color stage. Because 'blend' references gl_dst_alpha, the color value depends on the alpha value set in stage 2. Normally we would just put the alpha value directly in the image map, but this stage uses a 6 sided cube map texture, which moves with the viewer (because of texgen reflect). We don't want the alpha channel to move, however, so we have to set it in a different stage. 'red', 'green', and 'blue' being set to 'param0', 'param1', and 'param2' allow the level designer to change the color of the glass by changing the 'shaderParm' values in the editor. As you will see later, this could be shortened to just 'colored'

The fourth stage just blends a static image map on top.

Math and Logic
Materials in Doom 3 can contain mathematical and logical expressions. These expressions are evaluated for each material every frame, and are what cause normally boring surfaces to come alive. This is a replacement for the rather limited shader commands in Quake 3 such as tcMod scroll, rgbGen, etc.

Let's take a look at a material to see these features in use:

        if ( parm7 > 3 )
        blend add
        map models/weapons/soulcube/soulcube3fx
        rgb scTable[ time * .5 ] 

In Doom 3, certain stages of the material can be selectively turned on and off. The 'if' command in this example means "only draw this material if parm7 is greater than 3." There are a few places where parm7 can get set, one of them is in the editor with the 'shaderParm0' to 'shaderParm11' keys. Another place is in the script file (such as with weapons). Of course, it can also get set in the code.

Notice the use of a lookup table in this material. Here we are using 'time' (which is a floating point number that increases forever) to look up a value in 'scTable' (which was defined using a 'table' decl earlier).

The mathematical operators you can use in a material are %, /, *, -, and +. You can also use the boolean operators <, >, <=, >=, ==, !=, &&, and ||. The meaning of the symbols is the same as in C/C++, Java, PHP, etc. Mathematical expressions should be enclosed in parenthesis (there are cases where they don't have to be, such as when they are used as an index to a lookup table, but it never hurts to have too many. For the operands, you can use a lookup table, any numerical constant, and any of the following variables:

  • time: Forever increasing floating point value that returns the current time in seconds
  • parm0-parm11: Parameters that can be set a number of ways (discussed above)
  • global0-global7: Not used right now
  • fragmentPrograms: Constant that is 1 if ARB fragment programs are available. This is mostly used for disabling a stage by specifying "if ( fragmentPrograms == 1 )"
  • sound: The current sound amplitude of the entity using this material. This is used to create light materials that pulse with the sound.

Global Keywords for regular materials

qer_editorimage <map>Image to display in the editor
description <string>Just a simple description for people using this material
polygonOffset [float]offset the depth buffer to combat z-fighting
noShadowsDon't cast shadows
noSelfShadowThis material doesn't cast shadows on the model it's on (but it does on other models)
forceShadowsAllows nodraw surfaces to cast shadows
noOverlaysOverlay / Decal suppression
forceOverlaysForce decal overlays for alpha tested or translucent surfaces
translucentDraw with an alpha blend
clampDon't repeat the texture for texture coords outside [0, 1]
zeroclampguarantee 0,0,0,255 edge for projected textures
alphazeroclampGuarante 0 alpha edge for projected textures
forceOpaqueUsed for skies-behind-windows
twoSidedDraw the front and back. Implies no-shadows, because the shadow volume would be coplanar with the surface, giving depth fighting
backSidedDraw only the back. This also implies no-shadows
mirrorUse to make mirrors
noFogDon't fog this surface
unsmoothedTangentsUses the single largest area triangle for each vertex, instead of smoothing all
guisurf <guifile>
guisurf entity[2|3]
This surface has a gui on it. Use "somegui.gui" to specify the gui, or entity, entity2, entity3, etc for the level designer to set it in Radiant.
sort <type>Type is one of: subview, opaque, decal, far, medium, close, almostNearest, nearest, postProcess
spectrum <int>Spectrums are used for "invisible writing" that can only be illuminated by a light of matching spectrum
deform <type>See Below
decalInfo <staySeconds>
<fadeSeconds> [start rgb] [end rgb]
Used in decal materials to set how long the decal stays, and how it fades out.
renderbump <args...>Renderbump command options. See bump mapping
diffusemap <map>shortcut for
blend diffusemap
map <map>
specularmap <map>shortcut for
blend specularmap
map <map>
bumpmap <map>shortcut for
blend bumpmap
map <map>
DECAL_MACROshortcut for
polygonOffset 1
sort decal


spriteDeform the triangles of this surface to always face the viewer
tubePivot a rectangular quad along the center of its long axis
Note that a geometric tube with even quite a few sides tube will almost certainly render much faster than this, so this should only be for faked volumetric tubes. Make sure this is used with twosided translucent shaders, because the exact side order may not be correct.
flare <size>Build a translucent border that's always facing the viewer. This only works on quads (surfaces with 4 vertices). Used to make lens flares around lights.
expand <amount>Expand the surface along it's normals.
move <amount>Moves the surface along the X axis, mostly just for demoing the deforms. Example: deform move (time * 1)
turbulent <table> <range>
<timeoffset> <domain>
Turbulently deforms the S, and T values.
Example: deform turbulent sinTable 0.05 (time * 1) 10
eyeBallEach eyeball surface should have an separate upright triangle behind it, long end pointing out the eye, and another single triangle in front of the eye for the focus point. The texture coordinates on the eyeball surface will be deformed so that the center is lined up with the vector going from the origin triangle to the focus triangle.
particle <particleDecl>Emit particles from the surface instead of drawing it.
particle2 <particleDecl>Like particle, but ignores the surface area so small surfaces emit the same number of particles as large surfaces.

Global Keywords for light materials

noShadowsThis light doesn't cast shadows
forceShadowsfog, blend, and ambient lights don't cast shadows by default. This forces them to cast shadows
noPortalFogThis fog volume won't ever consider a portal fogged out
fogLightOption to fill with fog from viewer instead of light from center
blendLightPerform simple blending of the projection, instead of interacting with bumps and textures
ambientLightAn ambient light has non-directional bump mapping and no specular
lightFalloffImage <map>specifies the image to use for the third axis of projected light volumes

Global Surface Parameters

solidmay need to override a clearSolid
waterused for water
playerclipsolid to players
monsterclipsolid to monsters
moveableclipsolid to moveable entities
ikclipsolid to IK
bloodused to detect blood decals
triggerused for triggers
aassolidsolid for AAS
aasobstacleused to compile an obstacle into AAS that can be enabled/disabled
flashlight_triggerused for triggers that are activated by the flashlight
nonsolidclears the solid flag
nullNormalrenderbump will draw as 0x80 0x80 0x80, which won't collect light from any angle
areaportaldivides areas
qer_nocarvedon't cut brushes in editor
discretesurfaces should not be automatically merged together or clipped to the world, because they represent discrete objects like gui shaders mirrors, or autosprites
noFragmentdmap won't cut surface at each bsp boundary
slickaffects game physics (not implemented?)
collisioncollision surface. if a model has no collision surfaces, then all surfaces are considered collision surfaces
noimpactdon't make impact explosions or marks
nodamageno falling damage when hitting
ladderplayer can climb up this surface
nostepsno footstep sounds
metalSurface types for sound effects and blood splats

Stage Keywords

blend <type>
blend <src>, <dst>

Blend types:

bumpmapNormal map
diffusemapDiffuse map
specularmapSpecular map

Source blend modes:

gl_oneConstant 1
gl_zeroConstant 0
gl_dst_colorThe color currently on the screen
gl_one_minus_dst_colorOne minus the color currently on the screen
gl_src_alphaThe alpha channel of the source image
gl_one_minus_src_alphaOne minus the alpha channel of the source image
gl_dst_alphaThe alpha channel of the screen image
gl_one_minus_dst_alphaOne minus the alpha channel of the screen image
gl_src_alpha_saturateMinimum of the source alpha and one minus screen alpha

Destination blend modes:

gl_oneConstant 1
gl_zeroConstant 0
gl_src_colorThe color of the source image
gl_one_minus_src_colorOne minus the color of the source image
gl_src_alphaThe alpha channel of the source image
gl_one_minus_src_alphaOne minus the alpha channel of the source image
gl_dst_alphaThe alpha channel of the screen image
gl_one_minus_dst_alphaOne minus the alpha channel of the screen image
map <map>The image program to use for this stage
remoteRenderMap <int> <int>Width and Height of the buffer to render a remote image in to (for cameras). The entity this material is applied to has to support remote render views.
mirrorRenderMap <int> <int>Width and Height of the buffer to render a mirror in to. This of course makes this stage a mirror stage, which is different from using the 'mirror' global keyword because that makes the entire material a mirror, rather than just one stage.
videomap [loop] <file>This stage uses a video stream as an image map
soundmap [waveform]This stage uses a sound meter from the sound system as an image map. Specify 'waveform' to get a scope rather than bars.
cubeMap <map>This stage uses a cube map as the image map. Looks for _px, _py, _pz, _nx, _ny, _nz for the positive x, y, z, and negative x, y, z sides
cameraCubeMap <map>This stage uses a cube map in camera space. Looks for _forward, _back, _left, _right, _up, and _down
ignoreAlphaTestAlways use DEPTHFUNC_LEQUAL rather than DEPTHFUNC_EQUAL which is normally used for opaque and alpha tested surfaces
nearestUse nearest texture filtering
linearUse linear texture filtering
clampSame as the global keywords. Use to override a global clamp for a specific stage.
noclampUse to set texture repeat for a stage when global clamp is set
uncompressedDo not compress this image in medium quality mode
forceHighQualityDo not compress this image in low quality mode
nopicmipIgnore the image_downSize cvar
vertexColorMultiply the pixel color by the vertex color
inverseVertexColorMultiply the pixel color by one minus the vertex color
privatePolygonOffset <float>Explict larger (or negative) polygon offset for this stage
texGen <type>Type is one of: normal, reflect, skybox, wobbleSky <exp> <exp> <exp>
scroll <exp>, <exp>Scroll the texture coordinates
translate <exp>, <exp>
scale <exp>, <exp>Just scales without a centering
centerScale <exp>, <exp>Subtracts 0.5, then scales, then adds 0.5
shear <exp>, <exp>Subtracts 0.5, then shears, then adds 0.5
rotate <exp>Subtracts 0.5, then rotates, then adds 0.5
maskRedDon't write to the red channel
maskGreenDon't write to the blue channel
maskBlueDon't write to the green channel
maskAlphaDon't write to the alpha channel
maskColorShortcut for
maskDepthDon't write to the depth buffer
alphaTest <exp>Only write if the alpha value is greater than <exp>
red <exp>Set the red vertex color
green <exp>Set the green vertex color
blue <exp>Set the blue vertex color
alpha <exp>Set the alpha vertex value
rgb <exp>Shortcut for
red <exp>
green <exp>
blue <exp>
rgba <exp>Shortcut for
red <exp>
green <exp>
blue <exp>
alpha <exp>
color <exp0>, <exp1>, <exp2>, <exp3>Shortcut for
red exp0
green exp1
blue exp2
alpha exp3
coloredShortcut for
color parm0, parm1, parm2, parm3
if <exp>Conditionally disable stages
fragmentProgram <prog>Use an ARB fragment program with this stage
vertexProgram <prog>Use an ARB vertex program with this stage
program <prog>Shortcut for
fragmentProgram <prog>
vertexProgram <prog>
vertexParm <index> <exp0>
[,exp1] [,exp2] [,exp3]
Values to pass to the vertex program. One expression gets repeated across all 4 values. Two expressions put 0, 1 in z, w. Three expressions put 1 in w.
fragmentMap <index> [options] <map>The image map to use for texture unit <index>
[options] can be cubeMap, cameraCubeMap, nearest, linear, clamp, noclamp, zeroclamp, alphazeroclamp, forceHighQuality, uncompressed, highquality, or nopicmip
megaTexture <mega>This stage uses a mega texture (super secret)

Parameters Key

<float>Any number
<int>Any number without a fractional part
<string>Any value enclosed in quotes
<index>An integer number that is an index into an array
<map>An image map, which may include image programs (below)
<prog>A vertex / frament program. Written using the GL ARB shader language. These files are stored in the glprogs directory
<exp>An expression that is evaluated every frame.

Image Program Functions
These can be used anywhere that accepts <map> and can be nested

heightmap(<map>, <float>)Turns a grayscale height map into a normal map. <float> varies the bumpiness
addnormals(<map>, <map>)Adds two normal maps together. Result is normalized.
smoothnormals(<map>)Does a box filter on the normal map, and normalizes the result.
add(<map>, <map>)Adds two images without normalizing the result
scale(<map>, <float> [,float] [,float] [,float])Scales the RGBA by the specified factors. Defaults to 0.
invertAlpha(<map>)Inverts the alpha channel (0 becomes 1, 1 becomes 0)
invertColor(<map>)Inverts the R, G, and B channels
makeIntensity(<map>)Copies the red channel to the G, B, and A channels
makeAlpha(<map>)Sets the alpha channel to an average of the RGB channels. Sets the RGB channels to white.

Copyright 2004 id software