Detail props

Detail props create the foliage in this screenshot from Dear Esther.

Detail props are cheap, non-solid 3D objects that randomly emit from materials. They fade out at a distance (by default 1200 units), so are only good for small, surface-hugging features like grass tufts.

They generally take the form of "quads": two polygons forming a square, on which a $translucent material is applied. The prop can be configured to rotate so that it always faces the camera. While it is technically possible to use actual models as detail props, there is a significant DirectX overhead involved (Source does not support Geometry instancing) that makes doing so impractical.

Detail props can be configured to sway in the breeze, and to bend as players brush past.

Usage

"Detail groups" are defined in a .VBSP (an ANSI text file), then referenced with the material parameter %detailtype. VBSP generates detail props randomly when the map is compiled.

The default .VBSP file is root\detail.vbsp, but you can create your own as long as you remember to change the corresponding worldspawn setting (Map > Map Properties...).

Stock detail groups

These groups are available in Source SDK Base:

• swamp_land_002
• grass01
• grass02
• coastline_grass01
• coastline_grass02
• coastline_redgrass01
• coastline_redgrass02
• coastline_redgrass03
• citygrass01
• redgrass
• redgrass_light
• short_redgrass
• PerfTest1
• canal_reeds
• rocks_redgrass
• lostcoast_grass
• lostcoast_grass2

Todo: Screenshots

These groups are present but rely on unavailable models:

• swamp_land_001
• swamp_water_001
• grassland1
• grassland2
• grassland3
• rocks3
• test
• coast_pebbles
• street_junk

New detail groups

Here is a simple .VBSP file:

detail
{
	redgrass
	{
		density 2000

		Group1
		{
			alpha 1

			Model1
			{
				sprite "288 0 128 128 512"
				spritesize ".5 0 19 25"
				spriterandomscale .2
				amount .4
				detailOrientation 2
			}
			Model2
			{
				sprite "0 0 128 128 512"
				spritesize ".5 0 23 30"
				spriterandomscale .2
				amount .4
				detailOrientation 2
			}
			Model3
			{
				sprite "144 0 128 128 512"
				spritesize ".5 0 15 15"
				spriterandomscale .2
				amount .2
				detailOrientation 2
			}
		}

		Group2
		{
			alpha 0
		}
	}

	second_detail_group
	{
		// ...
	}
}

density

How frequently to generate a prop.

Todo: What's the equation?

Group<n>

You can group detail props together within the detail group. This lets you apply properties to many of them at once.

alpha

This does not define the alpha value of the detail prop, but instead the displacement alpha value at which the current subgroup has 100% influence. (Detail groups are most often used with WorldVertexTransition materials.)

Group2, further down in the example, is empty except for the command alpha 0. This means that the detail group will produce lots of props at alpha 1 and then smoothly degrade into nothing in regions with alpha 0 (i.e. the second WVT texture).

Model<n>

Defines an individual detail prop, regardless of whether it's a model or a quad.

Then, you can specify as many groups of detail props as you like. Materials on non-displacement surfaces will only use one group, but displacement surfaces may use multiple groups. Each group specifies a list of the models that will be randomly emitted. The model fields above describe which studio model to use, and the "amount" field describes how many to emit relative to the other models in the list. For advanced users: If the amounts of all the models within a single group add up to less than 1, then the system will actually emit less than the maximum number of models described by "density".

The "alpha" field is only used for displacement surfaces. When a displacement surface is using a material that blends between two textures, the alpha describes how much of each texture to use. The detail system looks at that alpha to choose which group to select models from. For example, lets say you've got a displacement with two textures on it, one is road (alpha = 1 for the road) and the other is grass (alpha = 0 for the grass). In the example above, it would emit rocks on the road and grass tufts on the grass, since the group with "alpha" "1.0" contains rock models and the group with "alpha" "0.0" contains grass models. Note that you can make as many groups as you want; for example, if you were to add a group with "alpha" "0.5", this would create detail props using that group's models wherever the displacement is blending halfway between the rocks and grass.

Using the detail prop system with .MDLs can actually be fairly expensive owing to a high per-model overhead that currently exists in DirectX. To avoid this, you may also use sprites with the detail prop system, which doesn't have this overhead and is consequently at least 10x faster than using .MDLs. Here's how to specify a detail model group that uses detail sprites:

Group1
{
	"alpha" "1"
	Model1
	{
		"sprite" "288 0 128 128 512" 
		"spritesize" "0.5 0.0 19 25"
		"spriterandomscale" "0.2"
		"amount" "0.2"
		"detailOrientation" "2"
	}
	Model2
	{
		"sprite" "0 0 128 128 512"
		"spritesize" "0.5 0.0 23 30"
		"spriterandomscale" "0.2"
		"amount" "0.1"
		"detailOrientation" "2"
		}
}

The textures for detail sprites must all be placed in sub-regions of the texture "materials\detail\detailsprites.vtf".

The first two numbers in the "sprite" field shown above specify the (X, Y) coordinate of the upper left corner of the sprite as it lies within the detailsprite.vtf texture. The next two numbers specify the width and height of the sprite. The final number is the size of the detailsprite.vtf texture in pixels.

The first two numbers in the "spritesize" line specifies the rotational center of the detail sprite in normalized coordinates: (0,0) specifies the lower left, and (1,1) specifies the upper right. In the example above, the rotational center of the sprite is halfway along the lower edge of the sprite. The final two numbers in the "spritesize" line indicate the width and height of the sprite in world units when it gets drawn.

"spriterandomscale" specifies a random amount to scale the width and height of the detail sprite (in the example, the sprite will be between 80% and 120% of the size indicated in the "spritesize" line).

Finally, "detailOrientation" specifies how the detail sprite will move. A value of 0 indicates that it will not rotate; 1 means that it will always face the camera, and 2 means it will rotate around its Z-axis to try to face the camera as best it can.

General Properties

Property	Comment
"density"	Specifies how many points to randomly generate. Larger numbers will generate more detail props.
"amount"	The ratio of a detail relative to the others in the group. Value: 0.0 => 1.0
"alpha"	Determines which alpha to use for blended displacement surfaces. 0.5 would be between the two textures. Value:0.0 => 1.0

Properties Specific to Sprites

Property	Comment
"sprite"	Specifies the sprite to use by selecting a region of detailsprites.vtf. The first two numbers specify the (X, Y) coordinate of the upper left corner of the sprite as it lies within the detailsprite.vtf texture. The next two numbers specify the width and height of the sprite. The final number is the size of the detailsprite.vtf texture in pixels.
"spritesize"	The first two numbers specify the rotational center of the detail sprite in normalized coordinates: (0,0) specifies the lower left, and (1,1) specifies the upper right (0.5, 0.0 usually suffice). The final two numbers in the "spritesize" line indicate the width and height of the sprite in world units when it gets drawn.
"spriterandomscale"	Specifies a random amount by which the sprite's size is scaled.
"detailOrientation"	0: Do not orient towards the player. 1: Always face the player. 2: Always face the player but rotate on the x and y axis only.

Properties Specific to Models

Property	Comment
"model"	Specifies which studio model to use.

Detail Shapes

Detail shapes are a new way for the engine to place auto-emitted detail props on a surface, as specified by the detail.vbsp file. Introduced in the Day of Defeat: Source release, detail shapes allow normal sprites to be placed in a variety of shapes.

In addition, sprites can now have a "swaying" motion, where the sprite leans forward and back.

Finally, these sprites are capable of being "displaced". That is, they will move away from players upon contact and then bounce back to their original orientation. Note that the sprites will continue to "sway" even when pushed out of their original position.

Usage

Detail shape functionality was added (silently) to Counter-Strike: Source with the HDR update on December 1, 2005, which indicates that this addition is linked to the HDR technology and thus will likely be added to the other Source games when they are updated with HDR.

Types of Detail Shapes

Detail shape of "tri"

Another "tri" with a small distance value

sprite_shape	Comment
"cross"	This makes a criss-cross shape. Places two sprites which cross over one-another in the middle.
"tri"	This makes a detail in the exploded prism shape (triangle). Places three sprites sitting equidistant from each other in a triangle formation.

Refining Detail Shapes

There are several properties for the detail.vbsp file which refine the shape of the detail sprites, as well as enhacing their aesthetic quality (such as the sway).

Property	Comment
"sway"	Percentage of cl_detail_max_sway ( default 5 ). Value: 0.0 => 1.0
"shape_angle"	Specific to "tri" shape. Degrees to angle out each of the leaves. Value: 0 => 90 (Untested)
"shape_size"	Specific to "tri" shape. Percentage of sprite width to separate each leaf. near 0 for a triangle shape, near 1 for a closer, criss-cross shape. Value: 0, 1 (Untested)

Related Console Commands

There are several clientside console commands you may use to alter the behavior of detail sprites.

Command	Comment
"cl_detail_avoid_force"	Force with which to avoid players.
"cl_detail_avoid_radius"	Radius around sprite to avoid players.
"cl_detail_avoid_recover_speed"	How fast to recover position after avoiding players.
"cl_detail_max_sway"	Amplitude of the detail prop sway.