Editing Darkplaces material system/Special Keywords

{{navigation title|General Keywords}}
{{unfinished}}

==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 use 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>====
: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_offset <nowiki><N.N></nowiki>====
:Offsets a surface along the vertex normals N.N game units.

====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_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).
:* '''rotate <nowiki><degrees></nowiki>''' - Rotates the texture (around origin, not center) a specified number of degrees.
:* '''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).
:* '''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_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.}}

===Per-vertex RGBA tweaks===
This keywords are used to tweak generation of per-vertex RGBA components which is normally used for [[vertex lighting]] and [[terrain blending]]/[[vertex controlled transparency]].

====q3map_colorMod <function>====
:Used to generate or modify RGB component on all surface vertices. Functions are:
:* '''set <nowiki>( <r> <g> <b> )</nowiki>''' - replace vertex RGB with supplied values.
:* '''scale <nowiki>( <r> <g> <b> )</nowiki>''' - multiplies RGB with supplied values.
:* '''dotproduct <nowiki>( <X> <Y> <Z> )</nowiki>''' - multiplies color by dotproduct of vertex normal and given vector.
:* '''dotproduct2 <nowiki>( <X> <Y> <Z> )</nowiki>''' - works in a similar way to dotproduct except it exaggerates the differences in vertex normals by squaring the final dot product value.
:* '''volume''' - a special keyword that lets a brush to affect all vertices inside it (see [[colormod brushes]]).

====q3map_alphaMod <function>====
:Work in similar way as q3map_colorMod but affects alpha component. Functions are:
:* '''set <nowiki><value>)</nowiki>''' - replace vertex alpha.
:* '''scale <nowiki><value>)</nowiki>''' - multiply vertex alpha.
:* '''dotproduct <nowiki>( <X> <Y> <Z> )</nowiki>''' - same thing as for q3map_colorMod.
:* '''random <nowiki><A.A> <B.B></nowiki>''' - sets the random alpha to vertexes in A-B range (this will keep junctions - vertices at same origin will receive same random value).
:* '''randomjitter <nowiki><A.A> <B.B></nowiki>''' - works like random but value gets added, not replaced.
:* '''randomscale <nowiki><A.A> <B.B></nowiki>''' - works like random but value is a multiplier.
:* '''volume''' - a special keyword that lets a brush to affect all vertices inside it (see [[colormod brushes]]).
:* '''wateralpha <nowiki><N.N></nowiki>''' - this sets alpha only on surfaces with surfaceparm water, lava or slime. Should be used in conjunction with '''q3map_alphaMod volume'''.
:* '''waterspring <nowiki><N.N></nowiki>''' - obsolete, dont use.
:* '''watermove <nowiki><A.A> <F.F></nowiki>''' - obsolete, dont use.
:* '''waterwarp <nowiki><N.N></nowiki>''' - obsolete, dont use.

====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 (eg. forcing per-vertex alpha component) 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_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====
:[[vertex lighting | Vertex lighting]] of a surface will be calculated using lightgrid's ''LightContributionToPoint'' function (instead of default ''LightContributionToSample'' which works for lightmaps).

===Area lights===

====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_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_lightmapSampleOffset <nowiki><distance></nowiki>====
: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<nowiki><self> <other></nowiki>====
: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}}

===Lighting tweaks===

====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_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|forceMeta is also applied by '''Lightmapped''' flag on misc_models}}

====q3map_shadeAngle <nowiki><angle></nowiki>====
: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}}

====q3map_lightmapSampleSize <nowiki><N></nowiki>====
: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_bounceScale <nowiki><value></nowiki>====
: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_normalImage <nowiki><texturePath></nowiki>====
:Specifies [[normalmap]] image to be used for calculating lightmap intensities. This will, effectively, bake normalmap-caused shading into lightmap.

==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 <nowiki><textureName></nowiki>===
: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 [[brush | 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 <nowiki><N.N></nowiki>===
: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 <nowiki><func> <N.N></nowiki>===
: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

{{navigation footer|Stages}}