Detail props

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

Detail props are cheap, non-solid 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 and shrubs.

There are two types of detail prop:

Sprite

Two polygons forming a square, covered with a $translucent material. The prop can be configured to rotate so that it always faces the camera, to sway in the breeze, and/or to bend as players brush past.

Model

Although supported, there is a significant per-model DirectX overhead (Source does not support geometry instancing) that makes them some ten times slower than sprites.

Usage

Types of detail prop cover ("detail types") are defined in a .VBSP script file (ANSI format), then referenced in materials with the %detailtype parameter. VBSP then generates detail props on the material randomly when the map is compiled.

Detail props can be placed manually with the prop_detail entity, but it only supports models so is rarely used.

Tip: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...). See #New detail types.

Stock detail types

These types 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 types are present but rely on unavailable models:

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

New detail types

Here is a custom .VBSP file (use this detail texture with it):

detail
{
	forest_floor_01
	{
		density 1600

		GrassTex
		{
			alpha 0
			RoseFlower
			{
				sprite "0 0 83 128 512"
				spritesize "0.5 0.05 7 13"
				spriterandomscale .3
				amount 0.02
			//	sprite_shape cross
				detailorientation 2
				sway 0.2
				upright 1
			}
			FernShrub
			{
				sprite "120 0 136 256 512"
				spritesize "0.5 0.05 17 28"
				spriterandomscale .15
				amount 0.03
				sprite_shape tri
				shape_size 0
				sway 0.3
			}
			GrassTuft
			{
				sprite "0 199 120 57 512"
				spritesize "0.5 0 20 10"
				spriterandomscale .2
				amount .6
				sprite_shape cross
				sway .1
			}
			PinkFlower
			{
				sprite "83 0 38 128 512"
				spritesize "0.5 0 6 18"
				spriterandomscale .1
				amount 0.02
				detailorientation 2
				sway 0.3
				upright 0
			}
			LushShrub
			{
				sprite "256 128 172 128 512"
				spritesize "0.5 0 32 21"
				spriterandomscale .3
				amount 0.01
				sprite_shape tri
				shape_size 0.1
				sway 0.1
			}
		}
		LeavesTex
		{
			alpha 1
			DriedGrass
			{
				sprite "256 0 92 120 512"
				spritesize "0.5 0 13 17"
				spriterandomscale .15
				amount .3
				sprite_shape cross
				sway .3
			}
			LushGrass
			{
				sprite "0 199 120 57 512"
				spritesize "0.5 0 20 10"
				spriterandomscale .2
				amount .6
				sprite_shape cross
				sway .1
			}
			RoseFlower
			{
				sprite "0 0 83 128 512"
				spritesize "0.5 0.05 7 13"
				spriterandomscale .3
				amount 0.01
				detailorientation 2
				sway 0.2
			}
		}
	}
}

The syntax is:

detail
{
	<Detail type>
	{
		density <float>

		<Group>
		{
			alpha <normal>

			<Prop>
			{
				<settings>
			}
		}
	}
}

The commands are:

Detail type

The name for use in %detailtype.

density <float>

How frequently to generate detail props on surfaces using this type. The equation is (surface area * density * 0.000001).

Group

Even if you are only defining one detail prop, you must create a group. The name doesn't seem to be used anywhere; it's just for reference.

alpha <normal>

The displacement alpha value on which the current prop group is generated. If alpha is undefined, all groups will appear in all areas.

Note:Non-displacement surfaces use only the first detail group!

Prop

Defines a detail prop. Although uniquely named, there is no way to reference an existing prop later on in the .VBSP: it must be redefined every time it's needed. It's still a good idea to use descriptive names, though!

Prop settings

amount <normal>

The proportion of the group that this model (or sprite) will account for. If the amount values of a group add up to less than 1, fewer detail props will be emitted than specified by density.

sprite <int|X, Y, W, H, VTF width>

The subregion of the map's detail material to use for this prop.

• X/Y are the top-left position
• W/H are the dimensions of the prop in texels
• VTF width is the X-axis resolution of the whole detail texture.
  Bug:In Valve's code any custom texture must be of the same aspect ratio as detail\detailsprites! Get the fix here.  [todo tested in ?]

spritesize <normal|U, V> <float|W, H>

The origin (U/V) and size in units (W/H) of the sprite when it is in the world.

spriterandomscale <normal>

The sprite's size will vary from 100% by this degree. A value of 1 means that the sprite could be generated at anything between 0% and 200% of its normal size.

detailOrientation <int>

How the sprite will react to the camera:

• 0: It will not rotate.
• 1: It will rotate around its origin to always face the camera head-on
• 2: It will rotate around its Z-axis only to face the camera. This is the most common setting, as it foreshortens the sprite while keeping it otherwise head-on.

upright <bool>

If present (with any value), the model will always point directly upwards. If not present, the model will angle itself according to the angle of the surface it is generated on.

minangle <float>

maxangle <float>

Used to control emission on steep surfaces. Default values for both are 180 (no restriction).

Tip:By setting a high minangle you can target overhangs.

Using models really isn't recommended, but should you want to:

model <string>

A model to use; must be $staticprop and UnlitGeneric (ALL skins). Include \models in the path.

Warning:Performance when using models is appalling!

Shapes

Shapes are props where two or three sprites are arranged in a 3D shape. They can be made to sway as if in a breeze, and can bend away from intersecting players.

Note:Detail shapes are only available in Day of Defeat: Source, Counter-Strike: Source and the SDK source code. To enable them in your mod, either compile with SDK_DLL or open \game\client\detailobjectsystem.cpp and remove the #ifdef from line 27.

If you try to create a shapes in a game without support for them, the detail props will not be created at all.

sprite_shape <choices>

Creates a set of sprites at different angles, allowing for a pseudo-3D effect.

tri

sprite_shape tri

Three sprites sitting equidistant from each other in a triangle formation.

cross

Two sprites which cross over one another in the middle.

sway <normal>

Percentage of cl_detail_max_sway that the prop bends to.

Tip:The prop don't need a sprite_shape to sway, but you do need shapes support in your game.

shape_angle <float>

sprite_shape tri only. Number of degrees outward at which to angle the individual sprites. Unfortunately it is not possible to angle inward, for some reason! Useful range is 0-45.

shape_size <normal>

sprite_shape tri only. Percentage of the sprites' width to put between them and the centre of the triangle. 0 means that the sprites cross at the prop's origin.

There are several console commands which affect shapes:

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.

If you can't find these, then your game doesn't have detail shape support.

New detail materials

The sample .VBSP's detail texture.

There are a few hoops to jump through when creating new detail sprite materials:

• Leave at least a one-pixel gap between subregions, or you may find parts of one sprite bleeding over into the next.
• The material must be UnlitGeneric. You'll probably want to use the $vertexcolor, $receiveflashlight, $nocull and $translucent parameters.
• Unless you are overwriting detail\detailsprites.vmt, mappers must remember to select the correct material in Map > Map Properties....

Bug:In Valve's code, detail textures at custom locations must be of the same aspect ratio as detail\detailsprites. You can fix this if you are shipping your own binaries.  [todo tested in ?]