Previous Index Next
3. General Shader Keywords
IMPORTANT NOTE: Once again, be aware that some of the shader commands may be order dependent, so it's good practice to place all global shader commands (keywords defined in this section) at the very beginning of the shader and to place shader stages at the end (see various examples).
These Keywords are global to a shader and affect all stages. They are also ignored by Q3MAP.
3.1 skyParms <farbox> <cloudheight> <nearbox>
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 cloud layers. 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 / 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 on top of the clouds. This has not been tested in a long time, so it probably doesn't actually work. Set to "-" to ignore.
Example: Sky script
} } }
q3map_sun1 1 0.5 15030 60
skyparms full 512 -
tcMod scroll 0.1 0.1
tcMod scale 3 2
tcMod scroll 0.05 0.05
tcMod scale 3 3
3.2 cull <side>
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 front if this keyword is not specified. However for items that should be inverted then the value back should be used. To disable culling, the value disable or none should be used. Only one cull instruction can be set for the shader.
3.2.1 cull front
The front or "outside" of the polygon is not drawn in the world. This is the default value. It is used if the keyword "cull" appears in the content instructions without a <side> value or if the keyword cull does not appear at all in the shader.
3.2.2 cull back
Cull back removes the back or "inside" of a polygon from being drawn in the world.
3.2.3 cull disable, cull 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.
3.3.1 deformVertexes wave <div> <func> <base> <amplitude> <phase> <freq>
Designed for water surfaces, modifying the values differently at each point. It accepts the standard wave functions of the type sin, triangle, square, sawtooth or inversesawtooth. The "div" parameter is used to control the wave "spread" - a value equal to the tessSize of the surface is a good default value (tessSize is subdivision size, in game units, used for the shader when seen in the game world) .
3.3.2 deformVertexes normal <div> <func> <base> <amplitude ~0.1-~0.5> <frequency ~1.0-~4.0>
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.
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. Some things that have been done with it: A small fluttering bat, falling leaves, rain, flags.
3.3.3 deformVertexes bulge <bulgeWidth> <bulgeHeight> <bulgeSpeed>
This forces a bulge to move along the given s and t directions. Designed for use on curved pipes.
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)
Design Note: 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.
3.3.4 deformVertexes move <x> <y> <z> <func> <base> <amplitude> <phase> <freq>
This keyword is used to make a brush, curve patch or md3 model appear to move together as a unit. The <x> <y> and <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> and <freq> values are the same as found in other wave form 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 Note: 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.
3.3.5 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.
Design Note: This is best used on objects that would appear the same regardless of viewing angle. An example might be a glowing light flare.
3.3.6 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.
3.4 fogparms <red value> <green value> <blue value> <distance to Opaque>
Note: you must also specify "surfaceparm fog" to cause q3map to identify the surfaces inside the volume. Fogparms only describes how to render the fog on the surfaces.
<red value> <green value> <blue value> 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.
<distance to opaque> 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)..
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.
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.
3.9 sort <value>
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):
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 blendfuncs) nearest (16): this shader should always sort closest to the viewer, e.g. muzzle flashes and blend blobs
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 blendfuncs)
nearest (16): this shader should always sort closest to the viewer, e.g. muzzle flashes and blend blobs
Previous Index Next
Quake 3: Arena Shader Manual Copyright 1999 id Software, Inc.
Revision 12 December 23, 1999
HTML by Jason Heppler
HTML Linking by Matthew "Bushboy" Trow