View source for Detail props

{{LanguageBar}}
{{update}}

[[File:Dear-esther henge.jpg|thumb|250px|Detail props create the foliage in this screenshot from {{Dear Esther|4}}.]]

[[File:Orion june2009 prev01.jpg|thumb|250px|Detail props are reflected by water in this [[Orion]] screen. Note the far hillside, beyond the fadeout distance.]]
[[File:Prison Island flora.jpg|thumb|250px|Detail props blend with [[prop_static|static props]] in [[Prison Island]].]]

'''Detail props''' are [[cheap]], non-solid objects that randomly emit from [[material|materials]] used by [[brush|brushes]] and [[displacements]]. 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:

; [[Sprite]]
: Two [[polygon]]s 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 (which soon becomes costly), 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.

{{modernConfirm|Verify if true: {{bug|In the vanilla shaders, only the first group defined in the {{mono|.vbsp}} file will work on [[LightmappedGeneric]]; any other group will not be applied to LightmappedGeneric (only [[WorldVertexTransition]]). As such, brushes ''must'' use the first group of the first detail type defined, and displacements should use WorldVertexTransition.}} }}
{{modernCodenote|Stock compilers limit the number of detail props to {{mono|65535}}. This is not an engine limit, and can technically be raised if necessary by modifying a sanity check in {{mono|AddDetailSpriteToLump}} from {{file|utils/vbsp/detailobjects|cpp}}.}}

== Usage ==

Types of detail prop cover ("detail types") are defined in a <code>.vbsp</code> script file (in ANSI format).
 
Detail props are referenced in materials (VMT file) with the '''<code>%detailtype</code>''' parameter (e.g. <code>"%detailtype" "grass01"</code>). 

[[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 and can be tedious (especially for sprites).

{{tip|The default VBSP file is <code>root\detail.vbsp</code>, but you can create your own as long as you remember to change the corresponding [[worldspawn]] setting (Map > Map Properties...). See [[#New detail types|New detail types (below)]].}}

== Stock detail types==


:{| class="standard-table mw-collapsible mw-collapsed" style="width: 400px;"
|+ style="text-align: left;" |These types are available in [[Source SDK Base]]

! Type || View 
|-
| swamp_land_002 ||
|-
| grass01 || [[File:Grass01.jpg|250px]] 
|-
| grass02 || [[File:Grass02.jpg|250px]]
|-
| coastline_grass01 || [[File:Coastline grass01.jpg|250px]]
|-
| coastline_grass02 || [[File:Coastline grass02.jpg|250px]]
|-
| coastline_redgrass01 || [[File:Coastline redgrass01.jpg|250px]]
|-
| coastline_redgrass02 || [[File:Coastline redgrass02.jpg|250px]]
|-
| coastline_redgrass03 || [[File:Coastline redgrass03.jpg|250px]]
|-
| citygrass01 || [[File:Citygrass01.jpg|250px]]
|-
| redgrass || [[File:Redgrass.jpg|250px]]
|-
| redgrass_light || [[File:Redgrass light.jpg|250px]]
|-
| short_redgrass || [[File:short redgrass.jpg|250px]]
|-
| canal_reeds || [[File:Canal reeds.jpg|250px]]
|-
| PerfTest1 ||
|-
| lostcoast_grass ||
|-
| lostcoast_grass2 ||
|}

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 [[#Shapes|detail shape support]]. Use [[:File:Detail forest.png|this detail texture]] with it.

<div style="max-height:30em;overflow:auto;"><source lang=ini>
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
			}
		}
	}
}
</source></div>

The syntax is:

<source lang=ini>
detail
{
	<Detail type>
	{
		density <float>

		<Group>
		{
			alpha <normal>

			<Prop>
			{
				<settings>
			}
		}
	}
}
</source>

The commands are:

; Detail type
: The name for use in <code>%detailtype</code>.
:; <code>density <[[float]]></code>
:: How frequently to generate detail props on surfaces using this type. The equation is (surface area * density * 0.000001). {{tip|<code>density 1000000</code> 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!}}
:; <code>alpha <[[normal]]></code>
:: 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 <code>alpha</code> 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 ===

; <code>amount <[[normal]]></code>
: The proportion of the group that this model (or sprite) will account for. If the <code>amount</code> values of a group add up to less than 1, fewer detail props will be emitted than specified by <code>density</code>.
; <code>upright <[[bool]]></code>
: 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.
; <code>minangle <float></code>
; <code>maxangle <float></code>
: Used to control emission on steep surfaces. Default values for both are 180 (no restriction). {{tip|By setting a high <code>minangle</code> you can target overhangs. 0 is a flat surface, 90 is straight up.}} 

==== Sprites ====

; <code>sprite <[[int]]|X, Y, W, H, VTF width></code>
: 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 [[texel]]s
:* 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 <code>detail\detailsprites</code>! [[Detail props/Aspect ratio fix|Get the fix here.]]}}
; <code>spritesize <normal|U, V> <[[float]]|W, H></code>
: The origin (U/V) and size in [[unit]]s (W/H) of the sprite when it is in the world.
; <code>spriterandomscale <normal></code>
: 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.
; <code>detailOrientation <int></code>
: 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.
{{note|In {{game link|Counter-Strike: Global Offensive}}, sprites seem to always use 2, ignoring what is set in the vbsp.}}
{{note|The detail texture will be stretched to a square with the same height as the VTF width. Consider this when setting the Y and H values.}}
{{note|The sprite is rendered inverted in the X-axis}}

==== Shapes ====

[[File:Detail shape tri.jpg|thumb|200px|<code>sprite_shape tri</code>]]
[[File:Detail shape cross.jpg|thumb|200px|<code>sprite_shape cross</code>]]
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|{{csgo}} sprite shapes work with [[UnlitGeneric]] and [[LightmappedGeneric]], but not [[Grass (Shader)|the grass shader]]}}
{{warning|Shapes place more load on the GPU, while sway places more load on the CPU. Use both as sparingly as possible. (The [[Dear Esther]] team have developed GPU-accelerated sway which is faster and more realistic, but their code is unreleased.)}}
{{bug|Shapes are extremely sensitive to shadows being cast onto them. If you encounter a shape completely dark while being lit (by the sun for example), increase the lightmaps value on your displacement surface or avoid using shapes at all.}}

{{note|Detail shapes are only available in some games, such as {{dods}}{{css}}{{CSGO}}{{gmod}} 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 <code>SDK_DLL</code> or open <code>\game\client\detailobjectsystem.cpp</code> and remove the <code>#ifdef</code> from line 27.}}}}

; <code>sprite_shape <choices></code>
: Creates a set of sprites at different angles, allowing for a pseudo-3D effect.
:; <code>tri</code>
:: Three sprites sitting equidistant from each other in a triangle formation.
:; <code>cross</code>
:: Two sprites which cross over one another in the middle.
; <code>sway <[[normal]]></code>
: Percentage of <code>cl_detail_max_sway</code> that the prop bends to. {{tip|The prop doesn't need a <code>sprite_shape</code> to sway, but you ''do'' need shape support in your game.}}
; <code>shape_angle <[[float]]></code>
: ''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.
; <code>shape_size <normal></code>
: ''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:

; <code>cl_detail_avoid_force</code>
: Force with which to avoid players.
; <code>cl_detail_avoid_radius</code>
: Radius around sprite to avoid players.
; <code>cl_detail_avoid_recover_speed</code>
: How fast to recover position after avoiding players.
; <code>cl_detail_max_sway</code>
: 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! 

{{warning|Keep a very low amount of models even if in game performance is alright. They will make the game/mod crash upon [[Cubemaps#Building_cubemaps|building cubemaps]], at least those based in SDK 2013. May not occur on modern branches, however. }}

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.

; <code>model <[[string]]></code>
: A [[model]] to use; must be [[$staticprop]] and <code>[[UnlitGeneric]]</code> (ALL skins). Include <code>\models</code> and <code>.mdl</code> in the path.

{{modernCodenote|To allow <code>[[VertexLitGeneric]]</code> models, open <code>game\client\detailobjectsystem.cpp</code> and remove the conditional block from <code>CDetailObjectSystem::UnserializeModelDict()</code>.}}

== New detail materials ==

[[File:Detail forest.png|thumb|200px|The [[#New detail types|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 use the <code>[[UnlitGeneric]]</code> or {{csgo|only}} <code>[[Grass (shader)|Grass]]</code> shader. You'll probably want to use the [[$vertexcolor]], [[$receiveflashlight]], [[$nocull]] and [[$translucent]] or [[$alphatest]] parameters.
:{{note|Detail sprite shapes will suffer from alpha sorting issues if using [[$translucent]]. [[$allowalphatocoverage]] is not supported for detail sprites. }}
* Unless you are overwriting <code>detail\detailsprites.vmt</code>, 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 <code>detail\detailsprites</code>. [[Detail props/Aspect ratio fix|You can fix this if you are shipping your own binaries.]]}}

== Blocking detail props ==

If you do not want to have detail props being generated in a specific area, use [[func_detail_blocker]] {{l4d|since}}{{gmod|also}}. If func_detail_blocker is not available in the target game, a duplicate VMT of the material could be made without the {{code|%detailtype}} parameter.

== Utilities ==

{{Xblahmt|4}}

[[File:XBLAH's Modding Tool - Detail Editor v1.18.1.png|thumb|392px|XBLAH's Modding Tool - Detail Editor.]]

Can create or edit detail props files (.vbsp). The editor shows a preview of the detail props, showing both sprites and props, and is integrated with the File Explorer to make it really easy to create new detail props. [[XBLAH's_Modding_Tool#Details_Editor|See more]].
[[Category:Level Design]]