Darkplaces material system/General Keywords

Revision as of 17:37, 26 July 2012

Darkplaces material system | previous chapter: Darkplaces material system

Contents 1 surfaceparm 1.1 General surfaceparms 1.2 System surfaceparms 1.3 Custom surfaceparms 2 cull none 3 deformVertexes 3.1 deformVertexes <wave> <div> <func> <base> <amplitude> <phase> <freq> 3.2 deformVertexes normal <div> <func> <base> <amplitude ~0.1-~0.5> <frequency ~1.0-~4.0> 3.3 deformVertexes bulge <bulgeWidth> <bulgeHeight> <bulgeSpeed> 3.4 deformVertexes move <x> <y> <z> <func> <base> <amplitude> <phase> <freq> 3.5 deformVertexes autosprite 3.6 deformVertexes autosprite2 3.7 Specific parameter definitions for deform keywords

surfaceparm

This is, by the fact, most widely used and most tricky material keyword.

All surfaceparm keywords are preceded by the word surfaceparm as follows: surfaceparm nonsolid or surfaceparm trans. Each surfaceparm have corresponding q3map_surfaceparmname keyword (q3map_nonsolid, q3map_trans etc.) which is only acquired by Q3map2. Surfaceparm keywords change the physical nature of the materials and the brushes that are marked with them. Changing any of these values will likely require the map to be re-compiled. These are global and affect the entire shader.

This document skips all Q3map2 surfaceparms that is not used by Blood Omnicide.

General surfaceparms

surfaceparm alphashadow

This keyword applied to a side on a brush, patch or model will cause the lighting phase of the Q3Map2 process to use the texture's alpha channel as a mask for casting static shadows in the game world.

Used by Q3map2 light phase.

 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. It is possible to increase the resolution of the lightmap receiving the shadows with a slight the cost of memory. This can be achieved with the q3map_lightmapSampleSize keyword on the shadow receiving shader or by creating a func_group of the shadow receiving brushes and adding the _ls key with a floating-point value for the scale of the lightmap.

surfaceparm detail

This surface attribute causes a brush to be ignored by the Q3Map2 process for generating possible break-points in the BSP tree. It functionality is same as marking brush as detail in level editor.

Used by Q3map2 BSP phase

surfaceparm lava

Assigns to the material the game properties set for lava. This affects contents of the brush.

Used by engine (BIH collision) and q3map2 (bsp phase).

 This keyword is used on common/ilava material.

surfaceparm lightfilter

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.

Used by Q3map2 light phase.

surfaceparm nodraw

Prevents Q3map2 from generating drawsurfaces for this material.

Used by Q3map2 BSP phase.

surfaceparm nomarks

Prevents engine from spawning decals for this surface.

Used by engine renderer.

 Use this on any surface with a deformVertexes keyword. Otherwise, the marks will appear on the unmodified surface location of the texture with the surface wriggles and squirms through the marks.

surfaceparm nolightmap

This surface will have no lightmap generated. This will save some memory and make map compilation faster.

Used by Q3map2 light phase.

{{design|This keyword have no effect at vertex-based lighting (lighting calculated for vertices and being saved to their rgba attributes). Surface with no lightmap will be rendered with vertex-based lighting. To disable vertex lignting calculation, use q3map_noVertexLight keyword.{{

surfaceparm nonsolid

Surface does not block the movement of entities in the game world. This affects the content of a brush. This still make q3map2 generate collision surfaces.

Used by engine (BIH collision) and q3map2 (bsp phase).

surfaceparm slime

Assigns to the material the game properties set for slime. In Blood Omnicide, slime is a swamp.

Used by engine (BIH collision) and q3map2 (bsp phase).

 This keyword is used on common/islime material.

surfaceparm trans

Tells Q3Map2 that pre-computed visibility should not be blocked by this surface.

Used by q3map2 BSP phase.

 Any materials that have blendfunc's should be marked as surfaceparm trans (anything behind them will not get culled).

surfaceparm water

Assigns to the material the game properties set for water. This affects both the surface and the content of a brush.

Used by engine (BIH collision) and q3map2 (bsp phase).

 This keyword is used on common/iwater material.

System surfaceparms

This is surfaceparms is only used in common materials. You dont need to specify them on your new materials.

surfaceparm hint

When Q3Map2 calculates the vis data, it tries to place portals in places in the map in an attempt to limit the potential viewable set (PVS). Brushes marked by a hint shader are used to manually place portals to force a break in the PVS.

Used by Q3map2 BSP phase. This keyword is used on common/hint material.

surfaceparm monsterclip

Surface with this flag will block NPC movement. Should be used with surfaceparm nonsolid.

Used by engine (collision). This keyword is used on common/monsterclip material. You dont need to specify it on your new materials.

surfaceparm lightgrid

The min/max bounds of brushes with this material in a map will define the bounds of the map's Lightgrid.

Used by Q3map2 light phase. This keyword is used on common/lightgrid material. You dont need to specify it on your new materials.

surfaceparm playerclip

Surface with this flag will block player movement. Should be used with surfaceparm nonsolid.

Used by engine (collision). This keyword is used on common/playerclip material.

surfaceparm origin

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.

Used by q3map2 BSP phase. This keyword is used on common/origin material

surfaceparm structural

This surface attribute causes a brush to be seen by the Q3Map2 process as a possible break-point in a BSP tree. It is used as a part of common/hint material. Generally speaking, any opaque material not marked as "detail" is, by default, structural, so you shouldn't need to specify this.

Used by q3map2 BSP phase.

Custom surfaceparms

This surface parameters are defined by custinfoparms.txt and used to assign a game-related properties to material, such as hit effect and step sound.

Blood Omnicide have this game-physics materials:

• grass
• ice
• dirt
• wood
• oldwood
• ground
• sand
• dullmetal
• brookwater
• glass
• fur
• marble
• hay
• slate
• flesh
• metal
• oldmetal
• stone
• oldstone
• plan

Important: Blood Omnicide allows only one game-physics surfaceparm per material.

cull none

Every surface of a polygon has two sides, a front and a back. Typically, we only see the front side. For example, a solid block you only show the front side. In some situations we see both (grates, screens etc.).

To "cull" means to remove. This keyword allows to disable side culling, so both sides of the surfaces would be visible.

 When making things like grates and screens with brushes, put the texture with the cull none property on one face only. On the other faces, use a non-drawing texture.

deformVertexes

This function performs a general deformation on the surface's vertexes, changing the actual shape of the surface before drawing the material. You can stack multiple deformVertexes commands to modify positions in more complex ways, making an object move in two dimensions, for instance.

deformVertexes <wave> <div> <func> <base> <amplitude> <phase> <freq>

Designed for water surfaces, modifying the values differently at each point. It accepts the standard waveform functions.

The "div" parameter is used to control the wave "spread" - a value equal to the tesselation distance (see q3map_tessSize, a subdivision size, in game units, used for the material when seen in the game world).

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 material options like lighting (especially specular) and environment mapping (see stage specific keywords for tcGen environment). If the materialdon't use normals in any of their calculations, there will be no visible effect.

IMPORTANT NOTE: In Darkplaces, offset mapping uses vertex normals for the calculations. deformVertexes normal most likely will mess it up.

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.

deformVertexes bulge <bulgeWidth> <bulgeHeight> <bulgeSpeed>

This forces a bulge to move along the given S and T directions. Designed for use on curved pipes.

deformVertexes move <x> <y> <z> <func> <base> <amplitude> <phase> <freq>

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

 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.

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.

 This is best used on objects that would appear the same regardless of viewing angle. An example might be a glowing light flare.

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.

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/

 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.