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.

Todo: What's the equation?

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.

model <string>

A model to use. Include \models in the path.

Todo: How to compile a detail model.

Note:If this is used, there is no need for any of the following commands (which all apply to sprites).

Warning:Performance when using models is appalling!

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.
  Note:The texture must be at a 2:1 aspect ratio!

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.

Shapes

Shapes are advanced sprites which can deform. This is used to create a "swaying in the breeze" effect, and to make them 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, no detail props will be created.

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:

• Confirm:The texture must be 2:1. If it is 512 pixels across it must be 256 pixels tall.
• 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 too.
• Unless you are overwriting detail\detailsprites.vmt, mappers must remember to select the correct material in Map > Map Properties....