Difference between revisions of "Detail props"

From Valve Developer Community
Jump to: navigation, search
m
Line 3: Line 3:
 
[[File:Prison Island flora.jpg|thumb|Detail props blend with [[prop_static|static props]] in [[Prison Island]].]]
 
[[File:Prison Island flora.jpg|thumb|Detail props blend with [[prop_static|static props]] in [[Prison Island]].]]
  
'''Detail props''' are ''[[cheap]]'', non-solid objects that randomly emit from [[material]]s. They fade out at a distance (by default 1200 [[unit]]s), so are only good for small, surface-hugging features like grass and shrubs.
+
'''Detail props''' are variating in cost, non-solid objects that randomly emit from [[material]]s. They fade out at a distance (by default 1200 [[unit]]s), so are only good for small, surface-hugging features like grass and shrubs.
  
 
There are two types of detail prop:
 
There are two types of detail prop:

Revision as of 20:09, 16 December 2010

Detail props create the foliage in this screenshot from Dear Esther.
Detail props are reflected by water in this Orion screen. Note the far hillside, beyond the fadeout distance.
Detail props blend with static props in Prison Island.

Detail props are variating in cost, 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. Cannot cross the surface of water.
Model
3D models should be used sparsely, if at all. There is a per-object DirectX overhead that becomes more and more pronounced as the number of models increases, regardless of how many polygons are being drawn.

Usage

Types of detail prop cover ("detail types") are defined in a .vbsp script file (in ANSI format), and 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 and prop_detail_sprite entities, but doing so is rare.

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.
Tip:Place func_detail_blocker (New with Left 4 Dead) to suppress detail sprites.

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

To do: 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. It requires detail shape support. 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
				detailorientation 2
				sway 0.2
				upright 1
				maxangle 70
			}
			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
				upright 1
				maxangle 50
			}
			GrassTuft
			{
				sprite "0 199 120 57 512"
				spritesize "0.5 0 20 10"
				spriterandomscale .2
				amount .6
				sprite_shape cross
				sway .1
				maxangle 95
			}
			PinkFlower
			{
				sprite "83 0 38 128 512"
				spritesize "0.5 0 6 18"
				spriterandomscale .1
				amount 0.02
				detailorientation 2
				sway 0.3
				upright 1
				maxangle 70
			}
			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
				maxangle 40
			}
		}
		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
				maxangle 95
			}
			GrassTuft
			{
				sprite "0 199 120 57 512"
				spritesize "0.5 0 20 10"
				spriterandomscale .2
				amount .6
				sprite_shape cross
				sway .1
				maxangle 95
			}
			RoseFlower
			{
				sprite "0 0 83 128 512"
				spritesize "0.5 0.05 7 13"
				spriterandomscale .3
				amount 0.02
				detailorientation 2
				sway 0.2
				upright 1
				maxangle 70
			}
		}
	}
}

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).
Tip:density 1000000 means one detail prop per unit. Values of 1000 to 1500 are generally used.
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.
Note:Non-displacement surfaces use only the first detail group!
alpha <normal>
The displacement alpha value on which the current prop group prefers to be generated. Every time a detail prop is generated, VBSP will choose from the group with the closest alpha value to the one at the current location. If alpha is undefined, all groups will appear in all areas.
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.
upright <bool>
If present (with any value), the model will always point directly upwards. If not present, the model will orient itself to the angle of the surface it sits 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.

Sprites

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

sprite_shape tri

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.

Detail shapes are only available in Day of Defeat: Source, Counter-Strike: Source and the SDK source code. If you try to create shapes in a game without support for them, the detail props will not be created at all.

Tip:To enable shapes in your mod, either compile with SDK_DLL or open \game\client\detailobjectsystem.cpp and remove the #ifdef from line 27.
sprite_shape <choices>
Creates a set of sprites at different angles, allowing for a pseudo-3D effect.
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 shape 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 there is no detail shape support.

Models

Remember that models have a performance overhead that sprites do not. Use them only when needed!

Good candidates for models are contiguous objects that need to spread out along the ground, like small rocks, fallen branches and ground-covering plants including ivy and brambles. Things that stand upright are better off as sprites or shapes.

model <string>
A model to use; must be $staticprop and UnlitGeneric (ALL skins). Include \models and .mdl in the path.
Tip:To allow VertexLitGeneric models, open game\client\detailobjectsystem.cpp and remove the conditional block from CDetailObjectSystem::UnserializeModelDict().

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.