 |
Nuclide
Software Development Kit for id Technology
|
|
Nuclide
Software Development Kit for id Technology
|
Here is a list of all the commands that can be contained within a material definition file, like a mat or a shader file.
There are three different kinds of commands:
Surface specific commands affect the entire surface, or sometimes whole brush-volume it belongs to. Example commands may be surfaceparm.
Stage/Layer specific commands only affect one part of the rendering stage. Generally anything within a sub-block of braces ({ }) is a stage. It defines a layer to draw on top of the surface.
Due to how simple most surfaces are, you don't have to define a stage. It is often enough to set program, diffuseMap and you're rendering a surface handled entirely by the GPU.
Some operations, such as deformVertexes or tcMod are done on the CPU. While you can use those, know that moving that action into a Shader Program is recommended.
alphaFunc <func>
Determines the alpha test function used when rendering this surface.
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 frame-buffer. 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.
alphaGen <func>
The alpha channel can be specified like the rgb channels. If not specified, it defaults to 1.0.
This rendering stage keyword is used in conjunction with the surfaceparm 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.
blendFunc <simplefunc>
blendFunc <srcBlend> <destBlend>
Blend functions are the keyword commands that tell the renderer how graphic layers are to be mixed together.
The most common blend functions are set up here as simple commands, and should be used unless you really know what you are doing.
This is a shorthand command for blendFunc GL_ONE GL_ONE. Effects like fire and energy are additive.
This is a 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.
Shorthand 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.
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 file.
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 pre-calculated 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.
The following values are valid for the Source Blend part of the equation.
The following values are valid for the Destination Blend part of the equation.
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.
If no blendFunc is specified then no blending will take place. That's just a fact of life.
depthFunc <func>
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).
depthWrite
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.
program defines which GLSL/HLSL shader to load for a defined material. It also accepts arguments that will recompile a shader with certain permutations. This is kinda ugly,
Starting in The Wastes 1.2, there are the following shader programs available to you:
rgbGen <func>
rgbGen wave <func> <base> <amp><phase> <freq>
Defines what vertex colors are set to for any given surface.
If no rgbGen is specified, either "identityLighting" or"identity" will be selected, depending on which blend modes are used.
Valid <func> parameters are const, wave, identity, identityLighting, entity, oneMinusEntity, fromVertex, and lightingDiffuse.
Follow this up with a vector of the color that you'd like the vertex colors to be set as. An example for green would be:
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.
Colors are assumed to be all white (1.0,1.0,1.0). All filters stages (lightmaps, etc) will get this by default.
Colors are grabbed from the entity's .colormod field.
Colors are grabbed from 1.0 minus the entity's .colormod field.
Introduced by FTE, same as entity, but will receive lighting similar to identityLighting on top of it.
Colors are filled in directly by the data from the map or model files. This is used for blending brushes and patches. It was used at one point to store primitive lighting, in case the lightmapped rendering path was to expensive (this is no longer available).
As rgbGen vertex, but inverted.
Design Note: This keyword would probably not be used by a level designer
Colors are computed using a standard diffuse lighting equation. It uses the vertex normals to illuminate the object correctly.
Design Note: -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 materials for items, characters, weapons, etc.
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 and inversesawtooth.
Baseline value. The initial RGB formula of a color (normalized).
Amplitude. This is the degree of change from the baseline value. In some cases you will want values outside the 0.0 to 1.0 range, but it will induce clamping (holding at the maximum or minimum value for a time period) instead of continuous change.
See the explanation for phase under the waveforms heading of Key Concepts.
Frequency. This is a value (NOT normalized) that indicates peaks per second.
tcGen <coordinate source>
Specifies how texture coordinates are generated and where they come from. Valid functions are base, lightmap and environment.
Base texture coordinates from the original art.
Lightmap texture coordinates.
Make this object environment mapped.
tcMod <func> [...]
Specifies how texture coordinates are modified after they are generated.
The valid functions for tcMod are rotate, scale, scroll, stretch and transform.
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:
Then the texture coordinates will be scaled then scrolled.
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).
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. 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 [clampmap](clampmap) 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)
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. The scroll speed is measured in "textures" per second. A "texture" is the dimension of the texture being modified and includes any previous material modifications to the original texture). 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 texture's original coordinates) at the rate of a half texture each second of travel.
This should be the LAST tcMod in a stage. Otherwise there maybe popping or snapping visual effects in some materials.
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.
base: A base value of one is the original dimension of the texture when it reaches the stretch stage. Inserting other '''values positive or negative in this variable will produce unknown effects.
amplitude: This is the measurement of distance the texture will stretch from the base size. It is measured, like scroll, in textures. A value of 1 here will double the size of the texture at its peak.
phase: See the explanation for phase under the deform vertexes keyword.
frequency: this is wave peaks per second.
func:
Transforms each texture coordinate as follows:
S' = s * m00 + t * m10 + t0 T' = s * m01 + t * m11 + t1
This is for use by programmers.
Applies turbulence to the texture coordinate. Turbulence is a back and forth churning and swirling effect on the texture.
The parameters for this are defined as follows:
freq: 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.
bemode <mode>
Filters which back end rendering features are drawn on top of the material. While you're not encouraged to be overriding this value, it is sometimes necessary.
These are the different modes that we can specify.
All light types will be drawn onto this surface.
Dynamic lights only.
Shadowmaps only.
Spotlights only.
Cubemap lights only.
Cubemap lights and shadowmaps only.
Cubemap lights and spotlights only.
Spot lights and shadowmaps only.
Cubemap lights, spot lights and shadowmaps only.
For skies that might cast rays.
Those are rendered to a frame buffer object (with everything else being depthdark) and is then applied to the screen as a post-processing effect.
Used mainly by shadow maps.
Black depth passes only. Used to draw a black world, when r_shadow_realtime_world_lightmaps is 0 for example.
Deferred lighting only.
Fog layer only.
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 material.
This is the default value. 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 or if the keyword cull does not appear at all in the shader.
Cull back removes the back or "inside" of a polygon from being drawn in the world.
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.
deformVertexes <func>
This command 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.
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.
This deformation affects the normals of a vertex without actually moving it, which will effect later material options like lighting and especially environment mapping. If the material stages don't use normals in any of their calculations, there will be no visible effect.
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.
This forces a bulge to move along the given s and t directions. Designed for use on curved pipes.
This keyword is used to make a brush, curve patch or 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 material does not actually change position, it only appears to.
Design Note: If an object is made up of surfaces with different materials, all must have matching deformVertexes move values or the object will appear to tear itself apart!
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 material 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.
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:
This is roughly defined as the size of the waves that occur. It is measured in game units. Smaller values create agreater 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 of the texture. A value of 100.0 is a good default value (which means your tessSize should be close to that for things tolook "wavelike").
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.
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.
The distance that the deformation moves away from the base value. See Wave Forms in the introduction for a description of amplitude. <phase> SeeWave Forms in the introduction for a description of phase)
See Wave Forms in the introduction for a description of frequency)
Design Note: The siv 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 siv values) that rose and fell dramatically (big amplitude values). While a small, quiet pool may move very little.
diffuseMap <texturepath/texturename>
Specifies the default texture asset to use on the diffuse/albedo pass of the material. This is the base texture in most cases. Some special materials used for special effects and the like might not have one. However surfaces such as floors, walls etc. certainly do. It will affect which texture is used to get color information from for lighting passes, etc.
fogParms <red value> <green value> <blue value> <distance to opaque>
Note: you must also specify "surfaceparm fog" to cause vmap 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. To obtain the values that define fog color 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).
Design Notes:
Additional shader passes may be placed on a fog brush, as with other brushes.
fte_clutter <model> <spacing> <scale min> <scale max> <z offset> <angle min> <angle max>
Similar to [vmap_surfaceModel (vmap_surfacemodel.md), however it'll place models at runtime. The density can be controlled via the cvar r_clutter_density.
fullbrightMap <texturepath/texturename>
The texture is essentially a fullbright overlay on top of the diffuse/albedomap.
Not all Shaders support them. In some, like the unlit shader, the diffusemap is always fullbright.
noMipmaps
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.
noPicMip
This causes the texture to ignore user-set values for the gl_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.
normalMap <texturepath/texturename>
Specifies the default texture to use for any normalmap operations. This depends heavily on which [GLSL program](Shaders) is used inside the later stages. The dynamic lights will use this to determine height information for light and shadows. So sometimes you want to skip setting this.
Check out our [Normal mapping guide](Normal_mapping_guide).
polygonOffset
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 variable. If no value is supplied a distance of 1 is assumed, however this is meant for backwards compatibility. Being explicit will help grepping values later in case you need to find all surfaces with just a polygonOffset of 1.
portal
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.
reflectCube <texturepath/cubemapname>
Specifies which cubemap to use on this material. By default, the engine will pass the nearest in-world cubemap instead.
reflectMask <texturepath/texturename>
Defines a texture that specifies which parts of a material will reveal a reflective material, such as a cubemap. This applies to standard FTEQW. In Nuclide the reflectmask is currently unused with the included shaders. If you want to apply reflectivity to your materials, use the alpha channel of your normalmap instead.
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). Some of the VMAP specific commands use this as a reference as to what skybox to use for color, intensity etc.
The renderer will take it into account only if you do not supply any Stages in the material.
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 / 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.
sort
Use this keyword to fine-tune the depth sorting of materials as they are compared against other materials in the game world. The basic concept is that if there is a question or a problem with materials drawing in the wrong order against each other, this allows the designer to create a hierarchy of which materials draws in what order.
The default behavior is to put all blended materials in sort "additive" and all other materials 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 mostly ascending priority):
It is generally recommended you stick to the keywords. The engine may introduce new ones and you will benefit from internal sorting parameters not clashing with yours whenever the engine may update them.
specularMap <texturepath/texturename>
Can set the specularity of the surface in relation to dlights. Specularity is the intensity of the light reflecting off the surface. In special cases some [GLSL programs](Shaders) might use the texture it for other purposes, too.
The surfaceparm keyword is not only read by the VMAP compiler, but also by the renderer. A few keywords will only apply to any one of them.
All surfaceparm keywords are preceded by the word surfaceparm as follows:
Commands that affect core functionality of a surface, or could impact the entire room or the gameplay surrounding it.
A brush marked with this keyword functions as an area portal, a break in the VMAP 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.
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 a sentrances 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 areaportal.
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.
Assigns to the texture the game properties set for lava. This affects both the surface and the content of a brush.
The player takes no damage if he falls onto a texture with this surfaceparm
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.
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 surfaceparm included in a texture should give it significantly reduced friction.
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 VMAP process as a possible break-point in a BSP tree. It is used as a part of the material 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.
Assigns to the texture the game properties for water.
Marks the desired surface as a climbable surface. This currently affects the entire volume.
Blocks all movement of vehicle entities through this surface.
When this surface is impacted, steam will leak out temporarily. Specific to The Wastes 1.3.
When this surface is impacted, water will leak out temporarily. Specific to The Wastes 1.3.
Reserved for custom games. This can be anything.
Reserved for custom games. This can be anything.
Reserved for custom games. This can be anything.
Reserved for custom games. This can be anything.
Reserved for custom games. This can be anything.
Reserved for custom games. This can be anything.
Reserved for custom games. This can be anything.
Commands that affect rendering of a surface, or the how surfaces are made to look by the compiler. These do not affect gameplay function.
This keyword applied to a texture on a brush, patch or model will cause the lighting phase of the VMAP process to use the texture's alpha channel as a mask for casting static shadows in the game world.
Design Note: 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.
Fog defines the brush as being a "fog" brush. This is a VMAP function that chops and identifies all geometry inside the brush. The General material keyword fogparms must also be specified to tell how to draw the fog.
Causes the VMAP 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 if an alpha is to be respected.
Read as "No DeeLight". A texture containing this parameter will not be affected or lit by dynamic lights, such as weapon effects. The VMAP compiler doesn't really care about this, but the renderer does.
A texture marked with nodraw will not visually appear in the game world. Most often used for triggers, clip brushes, origin brushes, and so on. Light will pass through it, therefore beware of bleeding issues when using nodraw/caulk textures with this.
Same as nodraw, but the engine won't draw it, whereas the VMAP compiler will react to the surface. So unlike nodraw, light will not pass through these surfaces.
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.
Blob shadows (aka r_shadows 1) also counts as a mark. So any surface that you don't want to see affected by shadows should receive this surfaceparm.
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.
Light will pass through this surface, but only if either alphashadow or lightfilter are applied. Tells VMAP that pre-computed visibility should not be blocked by this surface. Generally, any materials that have blendfuncs should be marked as surfaceparm trans.
Specifies which impact effects and footstep sounds are played when interacting with a given surface. Only one of them can be given at once:
Defines that the surface is of an 'alien' material. Affects impact sound and effects.
Defines that the surface is of flesh. Affects impact sound and effects.
Defines that the surface is foliage. Affects impact sound and effects.
Defines that the surface is of computer parts. Affects impact sound and effects.
Defines that the surface is of dirt. Affects impact sound and effects.
Defines that the surface is a vent. Affects impact sound and effects.
Defines that the surface is a grate. Affects impact sound and effects.
Defines that the surface is of metal. Affects impact sound and effects.
Defines that the surface is of glass. Affects impact sound and effects.
Defines that the surface is of sand. Affects impact sound and effects.
Defines that the surface is of a liquid. Affects impact sound and effects.
Defines that the surface is of snow. Affects impact sound and effects.
Defines that the surface is of kitchen/bathroom tiles. Affects impact sound and effects.
Defines that the surface is of wood. Affects impact sound and effects.
Defines that the surface is of concrete. Affects impact sound and effects.
vmap_backMaterial <material>
This allows a brush surface to use a different material 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.
vmap_backMaterial only works on brush faces. For this reason, it is often deprecated in favor of using [vmap_cloneMaterial](vmap_cloneMaterial) where the target material contains [vmap_invert](vmap_invert).
It can still be useful as a kind of shorthand.
vmap_backsplash <percent> <distance>
Controls the percentage of [surface light](vmap_surfaceLight) backsplash (how much light the emitting surface hits), as well as the distant away from the surface of which it is cast. This is really tricky to get right in tight areas, so put time aside to experiment.
The default backsplash amount is 5%, and the default distance is about 16 units.
vmap_baseMaterial <material>
Copies the vmap_/surfaceparm commands from the specified material into this one.
However, if you want to copy the appearance and only specify compiler-specific modifications, use [vmap_remapMaterial](vmap_remapMaterial).
vmap_bounce <scale>
Specifies the fraction of light to re-emit during a bounce pass on this surface.
vmap_cloneMaterial <material>
A material with this directive will inherit the target material's properties and appearance. Be careful, this can lead to an infinite loop if a cloning material references another cloning material or itself.
vmap_invert
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 material that is targeted by [vmap_cloneMaterial](vmap_cloneMaterial) for something similar to [vmap_backMaterial](vmap_backMaterial).
vmap_lightImage <texturepath>
By default, surface lights use the average color of the source image to generate the color of the light. vmap_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. vmap_lightImage should appear before qer_editorImage.
vmap_lightmapFilterRadius <lightmap filter radius> <light filter radius>
This is usually used on [light emitting materials](vmap_surfaceLight) to approximate finer subdivided lighting. It adds a gaussian blur effect to the lightmaps of either the material itself, or the surfaces affected by the material, or both. The values for **<lightmap filter radius>** and **<light filter radius>** are measured in world units of filtering (blurring) of lightmap data cast by any light sources.
**<lightmap filter radius>** Amount of blur set for the material itself to approximate for the [surface light's](vmap_surfaceLight) finer subdivided lighting. It should be set to 0 for sky materials since they don't have lightmaps.
**<light filter radius>**: Amount of blur set for other surfaces affected by this material's emitted light. It should be set just high enough to eliminate the "stadium shadow" effect sometimes produced by [light_environment](light_environment) or to smooth out the lighting on [surface lights](vmap_surfaceLight).
[vmap_lightmapFilterRadius](vmap_lightmapFilterRadius) should be placed before any light related material directives that you want it to affect.
vmap_lightmapMergable
When specified, the compiler will attempt to merge all surfaces using this material together onto lightmap sheets. This can drastically reduce the artifacts occuring on surfaces like terrain where precision issues might get you black spots along the lightmap seams. Definitely use this across large collections of surfaces on which you expect smooth transitions.
vmap_lightmapSampleOffset <float>
Takes a single parameter, defaulting to 1.0, which specifies how many units off a surface should the compiler 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 vmap_lightmapSampleOffset as a last resort.
vmap_lightmapSampleSize <int>
Surfaces using a material 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 sample size is 8, smaller numbers increases lightmap resolution. In general, you should stick with power of 2 values.
vmap_lightRGB <red color> <green color> <blue color>
Alternative to [vmap_lightImage (Material Command)](vmap_lightImage) and the automatic way of figuring out which light color a specified surface emits.
q3map_lightSubdivide <units>
Used on surface lights (see [vmap_surfaceLight (Material Command)](vmap_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 lightmap generation.
vmap_nodirty
This surface is not affected by dirt-mapping. The compiler baked variant of ambient occlusion.
vmap_offset <float>
Offsets a surface along the vertex normals by N.N units. Used in celshading for those black edges. This is the sort-of the compiler version of [polygonOffset](polygonOffset)
vmap_remapMaterial <material>
Allows the material to later become known as the specified material.
These materials should not contain anything but compiler-specific keywords.
For example, if you want a material that is **exactly like'' the specified**vmap_remapMaterial**in appearance, but with a specific**vmap_''' or surfaceparm characteristics, use this command.
However, if you want want just a material's vmap_/surfaceparm properties, use [vmap_baseMaterial](vmap_baseMaterial).
vmap_shadeAngle <degrees>
In short: At which angle the phong shading on a material breaks. If you set it to 0, basically no phong shading will ever be performed. The default shade angle in [VMAP](VMAP) is 40 degrees.
vmap_surfacelight <intensity>
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 [vmap_lightImage](vmap_lightImage) or [vmap_lightRGB](vmap_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.
If you want to change the distance/range of the surfacelight, use [vmap_surfacelightDistance](vmap_surfaceLightDistance).
vmap_surfaceLightDistance <scale>
Increases the range of a surfacelight. This is different from increasing the [vmap_surfaceLight (Material Command)](vmap_surfaceLight) value, as it'll travel much wider without affecting the total intensity of the light.
vmap_surfaceModel <modelpath> <density> <odds> <minscale> <maxscale> <minangle> <maxangle> <oriented>
A surface with vmap_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.
This will bake the models into the .bsp itself, creating an unnecessarily inflated map. Use [fte_clutter (Material Command)](fte_clutter) instead.
vmap_tessSize <amount>
Formely known as just tessSize.
The command 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](deformVertexes) keyword.
Abuse of this can create a huge number of triangles. This happens during BSP processing, so maps must be reprocessed for changes to take effect.
It can also be used on tesselating surfaces to make sure that tesselations are large, and thus, less costly in terms of triangles created.
The following commands are alter specific behaviour during the BSP compilation process. These are not respected by the engine, the renderer or the game-logic.
These assume you use vmap. If not, read the documentation for the tool that you use. This info may not always be useful for other compilers.
