Darkplaces material system/Special Keywords

Revision as of 01:38, 28 July 2012

Darkplaces material system | previous chapter: General Keywords

Q3Map2 Specific Keywords

All of q3map2 specific keywords are processed during map compile. If this keywords changes, recompiling the map is required for the changes to take effect.

General q3map keywords

q3map_globalTexture

This keyword disables texture coordinates optimization for texture projection on brushes (optimization tries to keep texture coordinates closer to 0-1 range), making them to be related to the world center, not brush. This is useful when applying tcMod scale to several adjastent brushes, which can be wrong if not using this parameter.

q3map_tessSize <amount>

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 keyword.

Important: Abuse of this can create a huge number of triangles.

q3map_invert

Inverts a surface normal. Works on brush faces, models and patches.

q3map_cloneShader <materialName>

A shader with this keyword will inherit the target shader's properties and appearance.

Important: Be careful, this can lead to an infinite loop if a cloning shader references another cloning shader or itself.

q3map_backShader <materialName>

This allows a brush to use a different shader on the back side of surface. By way of example, this would allow a water brush (or other) surfaces to have a different appearance when seen from the inside.

q3map_backShader is a better alternative to cull none because it is consistent with lighting. Drawback are that it produces more geometry data (larger loading times, more memory required), which may be abusing if surface is used too many times.

Tip: q3map_backShader is identical to q3map_cloneShader (with cloned shader having q3map_invert)

q3map_offset <N.N>

Offsets a surface along the vertex normals N.N game units.

q3map_forceMeta

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 material basis. This is required for lightmapped models.

Template:Tip:forceMets is also applied by '''Lightmapped''' flag on misc models

q3map_tcGen <function>

Generate new texture coordinates for a surface. Supports two functions which do the exact same thing. The only difference is in the math, ivector was designed to be more intuitive.

q3map_tcGen ivector ( Sx Sy Sz ) ( Tx Ty Tz )

Generate new texture coordinates for a surface. Projects a texture S units by T units along a chosen axis. q3map_tcGen vector ( 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.

q3map_tcMod <function>

This works in a similar manner to the stage-specific tcMod keyword, 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> <T> - Scales S (x) and T (y) texture coordinates. Scale 2 2 would halve the size of the texture (doubling the texture co-ordinates).
q3map_tcMod translate <S> <T> - Shifts texture coordinates by S, T amount. Translate 0.5 0 would shift it one-half in S, and none in T.

q3map_alphaLayers <backgroundIndex> <foregroundIndex>

This keyword is used to assist terrain blending. Q3map2 tries to remove a seams on the connected terrain blend materials; this is done by forcing both material to show the same texture at connection point. In order to do that, q3map2 need to know what texture is used in background and foreground layer of a material. Supplied indexes gives that info. All textures that is used for terrain blending should be indexed (eg terrain/grass is 1, terrain/ground is 2, terrain/rock is 3). For grass-ground blend - q3map_alphaLayer 1 2, for ground-rock blend - q3map_alphaLayers 2 3 etc.

q3map_noClip

Normally, Q3Map2 clips all faces to the BSP, and then takes the minimum polygon that encompasses all visible fragments. This keyword forces Q3Map2 to uses the original brush faces.

q3map_noTJunc

Read as "no T-Junc". With this option, surfaces with this material are not used for T-junction fixing.

Tip: q3map_noClip and q3map_noTJunc, used in combination will preserve mesh geometry exactly as you make it.

Lighting-related q3map keywords

q3map_nonplanar

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. This improves lightmapping of a curved brush faces covered by this material.

q3map_lightmapMergable

Allows 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.

q3map_noVertexLight

Material with this keyword will skip vertex light calculations entirely. This keyword should be in material if vertex RGBA data is used for some effect.

q3map_vertexPointSample<self> <other>

vertex lighting of a surface will be calculated using lightgrid's LightContributionToPoint function (instead of default LightContributionToSample which works for lightmaps).

q3map_skyLight <amount> <iterations>

Make surface to cast light. Amount is a brightness value, similar to what you would use in q3map_sunExt. 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.

q3map_sunExt <r> <g> <b> <intensity> <degrees> <elevation> <deviance> <samples>

This keyword 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. Parameters are:

r g b - Color of light. 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.
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 penumbra (half-shadow). General values up to 2 or 3 are acceptable. The real sun has a solid angle of about half a degree. This gives you much more realistic shadows from the sun.
samples - The number of random jitters distributed over the solid arc (16 is a good value).

Sky shaders should probably still have a q3map_skyLight value. The sun gives a strong directional light, but doesn't necessarily give the fill light needed to soften and illuminate shadows.

q3map_normalImage <texturePath>

Specifies normalmap image to be used for calculating lightmap intensities. This will, effectively, bake normalmap-caused shading into lightmap.

q3map_lightimage <texturepath/texturename>

The keyword q3map_lightimage generates lighting from the average color of the TGA image specified by the q3map_lightimage.

The keyword sequence for generating light on a q3map_skyLight should be ordered as follows:

q3map_lightimage (the texture providing the light and the color of the light)
qer_editorimage (the editor-only image used to select the source map for the texture)
the average color of the light emitted from the shader is calculated from the lightimage.

q3map_lightRGB <r> <g> <b>

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. Template:Tip:This does not affect bounced light in radiosity or lightfilter

q3map_lightmapSampleSize <N>

Surfaces using a material with this keyword will have the pixel size of the lightmaps set to (NxN). 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. The default lightmap sample size is 16 (can be overriden using -samplesize key of q3map2 light phase).

q3map_lightmapSampleOffset <distance>

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 splotches on lightmapped terrain.

q3map_lightmapFilterRadius<self> <other>

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. The self parameter can be set for skyLights for finer subdivided lighting, but should be set to 0 for sky shaders since they don't have lightmaps. The other parameter should be set just high enough to eliminate the "stadium shadow" effect sometimes produced by q3map_skyLight. 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.

Tip: q3map_lightmapFilterRadius should be placed before any light related shader directives that you want it to affect

q3map_bounceScale <value>

Use a number 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. Default bounce scale is 0.25.

q3map_shadeAngle <angle>

Specifies the breaking angle for smooth 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.

Tip: This keyword only affects light calculations, not real surface normals

Editor Specific Keywords

These keywords only affect the texture when it is seen and manipulated in the Radiant editor. They should be grouped with the surface parameters but ahead of them in sequence.

qer_editorImage <textureName>

This keyword makes level editor to display different texture in 3D viewport.

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.

Later, Q3map2 will use this texture to generate texture coordinates on brushes.

Conventions: All textures supplied for qer_editorImage should be stored in radiant/ folder (like radiant/textures/town/wall1_1, radiant/models/mapobjects/crypt/statue1 etc.)

Design Notes: It is useful to always specify qer_editorImage on materials that could be used on brushes. This will separate material's real texture from the editor texture and give ability to replace game real texture with upscaled/downscaled one without re-editing a map.

qer_trans <N.N>

This keyword defines the percentage of transparency that a surface 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 surface is 20% opaque and nearly invisible.

qer_alphaFunc <func> <N.N>

If material have alphaFunc, this keyword will make it to be rendered with alpha test in level editor too.

Functions are:

greater - greater than
gequal - greater or equal
lesser - lesser than
lequal - lesser or equal
equal - equal

Next chapter: Stages
Back to index | Top of the page

@@ Line 6: / Line 6: @@
 All of q3map2 specific keywords are processed during map compile. If this keywords changes, recompiling the map is required for the changes to take effect.
-'''q3map_globalTexture'''
+===General q3map keywords===
+====q3map_globalTexture====
 :This keyword disables texture coordinates optimization for texture projection on [[Brush | brushes]] (optimization tries to keep texture coordinates closer to 0-1 range), making them to be related to the world center, not brush. This is useful when applying '''tcMod scale''' to several adjastent brushes, which can be wrong if not using this parameter.
-'''q3map_tessSize <nowiki><amount></nowiki>'''
+====q3map_tessSize <nowiki><amount></nowiki>====
 :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 keyword.
-{{Important|Abuse of this can create a huge number of triangles.}}
+:{{Important|Abuse of this can create a huge number of triangles.}}
+====q3map_invert====
+:Inverts a surface normal. Works on brush faces, models and patches.
+====q3map_cloneShader <nowiki><materialName></nowiki>====
+:A shader with this keyword will inherit the target shader's properties and appearance.
+:{{important|Be careful, this can lead to an infinite loop if a cloning shader references another cloning shader or itself.}}
+====q3map_backShader <nowiki><materialName></nowiki>====
+:This allows a brush to use a different shader on the back side of surface. By way of example, this would allow a water brush (or other) surfaces to have a different appearance when seen from the inside.
+:{{design|q3map_backShader is a better alternative to '''cull none''' because it is consistent with lighting. Drawback are that it produces more geometry data (larger loading times, more memory required), which may be abusing if surface is used too many times.}}
+:{{tip|q3map_backShader is identical to q3map_cloneShader (with cloned shader having q3map_invert)}}
+====q3map_offset <nowiki><N.N></nowiki>====
+:Offsets a surface along the vertex normals N.N game units.
+====q3map_forceMeta====
+: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 material basis. This is required for lightmapped models.
+:{{tip:forceMets is also applied by '''Lightmapped''' flag on misc_models}}
+====q3map_tcGen <nowiki><function></nowiki>====
+:Generate new texture coordinates for a surface. Supports two functions which do the exact same thing. The only difference is in the math, ivector was designed to be more intuitive.
+====q3map_tcGen ivector ( Sx Sy Sz ) ( Tx Ty Tz )====
+:Generate new texture coordinates for a surface. Projects a texture S units by T units along a chosen axis. q3map_tcGen vector ( 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.
+====q3map_tcMod <nowiki><function></nowiki>====
+:This works in a similar manner to the stage-specific tcMod keyword, 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 <nowiki><degrees></nowiki>''' - Rotates the texture (around origin, not center) a specified number of degrees.
+:* '''q3map_tcMod scale <nowiki><S> <T></nowiki>''' - Scales S (x) and T (y) texture coordinates. Scale 2 2 would halve the size of the texture (doubling the texture co-ordinates).
+:* '''q3map_tcMod translate <nowiki><S> <T></nowiki>''' - Shifts texture coordinates by S, T amount. Translate 0.5 0 would shift it one-half in S, and none in T.
+====q3map_alphaLayers <nowiki><backgroundIndex> <foregroundIndex></nowiki>====
+:This keyword is used to assist terrain blending. Q3map2 tries to remove a seams on the connected terrain blend materials; this is done by forcing both material to show the same texture at connection point. In order to do that, q3map2 need to know what texture is used in background and foreground layer of a material. Supplied indexes gives that info. All textures that is used for terrain blending should be indexed (eg terrain/grass is 1, terrain/ground is 2, terrain/rock is 3). For grass-ground blend - q3map_alphaLayer 1 2, for ground-rock blend - q3map_alphaLayers 2 3 etc.
+====q3map_noClip====
+:Normally, Q3Map2 clips all faces to the BSP, and then takes the minimum polygon that encompasses all visible fragments. This keyword forces Q3Map2 to uses the original brush faces.
+====q3map_noTJunc====
+:Read as "no T-Junc". With this option, surfaces with this material are not used for T-junction fixing.
+:{{tip|q3map_noClip and q3map_noTJunc, used in combination will preserve mesh geometry exactly as you make it.}}
+=== Lighting-related q3map keywords ===
+====q3map_nonplanar====
+: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. This improves lightmapping of a curved brush faces covered by this material.
+====q3map_lightmapMergable====
+:Allows 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.
+====q3map_noVertexLight====
+:Material with this keyword will skip vertex light calculations entirely. This keyword should be in material if vertex RGBA data is used for some effect.
+====q3map_vertexPointSample<nowiki><self> <other></nowiki>====
+:[[vertex lighting]] of a surface will be calculated using lightgrid's LightContributionToPoint function (instead of default LightContributionToSample which works for lightmaps).
+====q3map_skyLight <nowiki><amount> <iterations></nowiki>====
+:Make surface to cast light. Amount is a brightness value, similar to what you would use in '''q3map_sunExt'''. 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.
+====q3map_sunExt <nowiki><r> <g> <b> <intensity> <degrees> <elevation> <deviance> <samples></nowiki>====
+:This keyword 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. Parameters are:
+:* '''r g b''' - Color of light. 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.
+:* '''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 penumbra (half-shadow). General values up to 2 or 3 are acceptable. The real sun has a solid angle of about half a degree. This gives you much more realistic shadows from the sun.
+:* '''samples''' - The number of random jitters distributed over the solid arc (16 is a good value).
+:{{design|Sky shaders should probably still have a q3map_skyLight value. The sun gives a strong directional light, but doesn't necessarily give the fill light needed to soften and illuminate shadows.}}
+====q3map_normalImage <nowiki><texturePath></nowiki>====
+:Specifies [[normalmap]] image to be used for calculating lightmap intensities. This will, effectively, bake normalmap-caused shading into lightmap.
+====q3map_lightimage <nowiki><texturepath/texturename></nowiki>====
+:The keyword q3map_lightimage generates lighting from the average color of the TGA image specified by the q3map_lightimage.
+:The keyword sequence for generating light on a q3map_skyLight should be ordered as follows:
+:# q3map_lightimage (the texture providing the light and the color of the light)
+:# qer_editorimage (the editor-only image used to select the source map for the texture)
+:# the average color of the light emitted from the shader is calculated from the lightimage.
+====q3map_lightRGB <nowiki><r> <g> <b></nowiki>====
+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.
+{{tip:This does not affect bounced light in radiosity or lightfilter}}
-'''q3map_backShader &lt;shadername&gt;'''
+====q3map_lightmapSampleSize <nowiki><N></nowiki>====
-This allows a brush to use a different shader on the back side of surface. By way of example, this would allow a water brush (or other) surfaces to have a different appearance when seen from the inside.
+Surfaces using a material with this keyword will have the pixel size of the lightmaps set to (NxN). 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. The default lightmap sample size is 16 (can be overriden using -samplesize key of q3map2 light phase).
-{{design|q3map_backShader is a better alternative to '''cull none''' because it is consistent with lighting. Drawback are that it produces more geometry data (larger loading times, more memory required), which may be abusing if surface is used many times.}}
- '''q3map_sun <nowiki><red> <green> <blue> <intensity> <degrees> <elevation></nowiki>'''
+====q3map_lightmapSampleOffset <nowiki><distance></nowiki>====
- This keyword in a sky shader will create the illusion of light cast into a map by a single, infinitely distance light source (sun, moon, hellish fire, etc.). This is only processed during the lighting phase of  q3map.
+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 splotches on lightmapped terrain.
- <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> is 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> is the angle relative to the directions on the map file. A setting of 0 degrees equals east. 90 is north, 180 is west and 270 is south.
- <elevation> is 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
- {{design|Sky shaders should probably still have a q3map_surfacelight 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 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.}}
- Design Trick: Not certain what color formula you want to use for the sun's light? Try this. Create a light entity. Use the Q3Radiant 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.
- '''q3map_surfaceLight <nowiki><light value></nowiki>'''
+====q3map_lightmapFilterRadius<nowiki><self> <other></nowiki>====
- The texture gives off light equal to the <light 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 qer_lightimage keyword 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.
+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. The self parameter can be set for skyLights for finer subdivided lighting, but should be set to 0 for sky shaders since they don't have lightmaps. The other parameter should be set just high enough to eliminate the "stadium shadow" effect sometimes produced by q3map_skyLight. 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.
+{{tip|q3map_lightmapFilterRadius should be placed before any light related shader directives that you want it to affect}}
- '''q3map_lightimage <nowiki><texturepath/texturename></nowiki>'''
+====q3map_bounceScale <nowiki><value></nowiki>====
- The keyword q3map_lightimage generates lighting from the average color of the TGA image specified by the q3map_lightimage.
+Use a number 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. Default bounce scale is 0.25.
- The keyword sequence for generating light on a q3map_surfacelight should be ordered as follows:
-) q3map_lightimage ; (the texture providing the light and the color of the light)
-) qer_editorimage ; (the editor-only image used to select the source map for the texture)
-) the average color of the light emitted from the shader is calculated from the lightimage.)
- '''q3map_lightsubdivide <nowiki><value></nowiki>'''
+====q3map_shadeAngle <nowiki><angle></nowiki>====
- This allows the user to define how large, or small to make the subdivisions (triangles) in a textured surface, particularly aimed at light-emitting textures like skies. It defaults to 120 game units, but can be made larger (256 or 512) for sky boxes or smaller for light surfaces at the bottoms of cracks. This can be a dominant factor in processing time for q3map lighting.
+Specifies the breaking angle for smooth 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.
+{{tip|This keyword only affects light calculations, not real surface normals}}
 ==Editor Specific Keywords==