Detail props: Difference between revisions

From Valve Developer Community
Jump to navigation Jump to search
(→‎Usage: Added table of all the properties)
No edit summary
 
(131 intermediate revisions by 38 users not shown)
Line 1: Line 1:
[[Category:Level Design]]
{{LanguageBar}}
=Introduction=
{{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, or 4096 in {{hl2}} 20th anniversary and {{portal}} May 2025 update), 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|hidetested=1|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}}. Raising it too high can cause performance issues, however.}}
{{warning|{{l4d2|3}} has mutually exclusive detail props. You may not be able to mix nature materials because it would show broken detail props. See [[L4D2_Level_Design/L4D2_Detail_props|L4D2 Detail props]] for more info.}}
== 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.


Models of type [[prop_detail]] can be set to be randomly emitted from surfaces based upon the [[material]] assigned to the surface. The file <code>detail.vbsp</code> describes detail prop groups. Each detail prop group specifies which <code>prop_detail</code> models are emitted from that group. A material can indicate which detail prop group is assigned to it by adding this line to the [[VMT|.vmt]] file:
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).


<pre>
{{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)]].}}
%detailtype = "detail_group_name"
</pre>


Where <code>detail_group_name</code> is the one of the detail prop group entries in <code>detail.vbsp</code>.
== Stock detail types==


==Usage==


Here's an simple example of a detail prop group, as defined in <code>detail.vbsp</code>:
:{| class="standard-table mw-collapsible mw-collapsed" style="width: 400px;"
|+ style="text-align: left;" |These types are available in [[Source SDK Base]]


<pre>
! Type || View
  swamp_grass_and_rocks
|-
  {
| swamp_land_002 ||
      "density" "800.0"
|-
      Group1
| grass01 || [[File:Grass01.jpg|250px]]
      {
|-
        "alpha" "1.0"
| grass02 || [[File:Grass02.jpg|250px]]
        Model1
|-
        {
| coastline_grass01 || [[File:Coastline grass01.jpg|250px]]
          "model" "models/junk/rock1.mdl"
|-
          "amount" "0.3"
| coastline_grass02 || [[File:Coastline grass02.jpg|250px]]
        }
|-
        Model2
| coastline_redgrass01 || [[File:Coastline redgrass01.jpg|250px]]
        {
|-
          "model" "models/junk/rock2.mdl"
| coastline_redgrass02 || [[File:Coastline redgrass02.jpg|250px]]
          "amount" "0.3"
|-
        }   
| coastline_redgrass03 || [[File:Coastline redgrass03.jpg|250px]]
      }
|-
     
| citygrass01 || [[File:Citygrass01.jpg|250px]]
      Group2
|-
      {
| redgrass || [[File:Redgrass.jpg|250px]]
        "alpha" "0.0"
|-
        Model1
| redgrass_light || [[File:Redgrass light.jpg|250px]]
        {
|-
          "model" "models/foliage/Grass_tuft_003a.mdl"
| short_redgrass || [[File:short redgrass.jpg|250px]]
          "amount" "0.1"
|-
        }
| canal_reeds || [[File:Canal reeds.jpg|250px]]
        Model2
|-
        {
| PerfTest1 ||
          "model" "models/foliage/Grass_tuft_004b.mdl"
|-
          "amount" "0.3"
| lostcoast_grass ||
        }
|-
      }
| lostcoast_grass2 ||
  }  
|}
</pre>


<code>"Density"</code> describes how many points to randomly generate on all surfaces that have materials that use this detail prop group. Larger numbers will generate more detail props.
These types are present but rely on unavailable models:


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 <code>model</code> fields above describe which studio model to use, and the <code>"amount"</code> 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 <code>"density"</code>.
* swamp_land_001
* swamp_water_001
* grassland1
* grassland2
* grassland3
* rocks3
* test
* coast_pebbles
* street_junk


The <code>"alpha"</code> field is only used for displacement surfaces. When a displacement surface is using a material that blends between two [[texture]]s, 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 (<code>alpha = 1</code> 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 <code>"alpha" "1.0"<code> contains rock models and the group with <code>"alpha" "0.0"</code> contains grass models. Note that you can make as many groups as you want; for example, if you were to add a group with <code>"alpha" "0.5"</code>, this would create detail props using that group's models wherever the displacement is blending halfway between the rocks and grass.
== New detail types==


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:
Here is a custom .VBSP file. It requires [[#Shapes|detail shape support]]. Use [[:File:Detail forest.png|this detail texture]] with it.


<pre>
<div style="max-height:30em;overflow:auto;"><source lang=ini>
Group1
detail
{
{
"alpha" "1"
forest_floor_01
Model1
{
{
"sprite" "288 0 128 128 512"  
density 1600
"spritesize" "0.5 0.0 19 25"
GrassTex
"spriterandomscale" "0.2"
{
"amount" "0.2"
alpha 0
"detailOrientation" "2"
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
}
}
}
}
Model2
}
</source></div>
 
The syntax is:
 
<source lang=ini>
detail
{
<Detail type>
{
{
"sprite" "0 0 128 128 512"
density <float>
"spritesize" "0.5 0.0 23 30"
 
"spriterandomscale" "0.2"
<Group>
"amount" "0.1"
{
"detailOrientation" "2"
alpha <normal>
 
<Prop>
{
<settings>
}
}
}
}
}
}
</pre>
</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.}}


The textures for detail sprites must all be placed in sub-regions of the texture <code>"materials\detail\detailsprites.vtf"</code>.
==== Sprites ====


The first two numbers in the <code>"sprite"</code> field shown above specify the (X, Y) coordinate of the upper left corner of the sprite as it lies within the <code>detailsprite.vtf</code> 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.
; <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|hidetested=1|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 {{csgo|1}}, 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}}


The first two numbers in the <code>"spritesize"</code> 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 <code>"spritesize"</code> line indicate the width and height of the sprite in world units when it gets drawn.
==== Shapes ====


<code>"spriterandomscale"</code> 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 <code>"spritesize"</code> line).
[[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|hidetested=1|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.}}


Finally, <code>"detailOrientation"</code> 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.
{{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.}}}}


===General Properties===
; <code>sprite_shape <choices></code>
{|
: Creates a set of sprites at different angles, allowing for a pseudo-3D effect.
!width="100"|Property
:; <code>tri</code>
!Comment
:: Three sprites sitting equidistant from each other in a triangle formation.
|-
:; <code>cross</code>
| <code>"density"</code> || Specifies how many points to randomly generate. Larger numbers will generate more detail props.
:: Two sprites which cross over one another in the middle.
|-
; <code>sway <[[normal]]></code>
| <code>"amount"</code> || The ratio of a detail relative to the others in the group.
: 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.}}
'''Value''': 0.0 => 1.0
; <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>"alpha"</code> || Determines which alpha to use for blended displacement surfaces. <code>0.5</code> would be between the two textures.
; <code>shape_size <normal></code>
'''Value''':0.0 => 1.0
: ''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.
|}


===Properties Specific to Sprites===
There are several console commands which affect shapes:
{|
!width="100"|Property
!Comment
|-
| <code>"sprite"</code> || Specifies the sprite to use by selecting a region of <code>[[detailsprites.vtf]]</code>. 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.
|-
| <code>"spritesize"</code> || 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. The final two numbers in the "spritesize" line indicate the width and height of the sprite in world units when it gets drawn (0.5, 0.0 usually suffice).
|-
| <code>"spriterandomscale"</code> || Specifies a random amount by which the sprite's size is scaled.
|-
| <code>"detailOrientation"</code> || '''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.
; <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.


===Properties Specific to Models===
If you can't find these, then there is no detail shape support.
{|
!width="100"|Property
!Comment
|-
| <code>"model"</code> || Specifies which studio model to use.
|}


=Detail Shapes=
==== Models ====


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.
Remember that models have a performance overhead that sprites do not. Use them only when needed!


In addition, sprites can now have a "swaying" motion, where the sprite ''leans'' forward and back.
{{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. }}


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


==Usage==
; <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.


Currently, detail shapes are only functional for Day of Defeat: Source and Counter-Strike: Source. Other Source-based games lack the cl_detail_ console commands (and, thus, the underlying code) which are part of the implementation for the correct functioning of them.
{{modernCodenote|To allow <code>[[VertexLitGeneric]]</code> models, open <code>game\client\detailobjectsystem.cpp</code> and remove the conditional block from <code>CDetailObjectSystem::UnserializeModelDict()</code>.}}


With the release of the latest [[SDK Beta]], the bundled compile tools can now correctly interpret the new configurations for setting detail shapes and will create the detail_prop entities accordingly. Note that this will only work for Day of Defeat: Source and Counter-Strike: Source, as the other Source-based games have not yet been updated to handle the display of detail shapes.
== New detail materials ==


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.
[[File:Detail forest.png|thumb|200px|The [[#New detail types|sample .VBSP]]'s detail texture.]]


==Types of Detail Shapes==
There are a few hoops to jump through when creating new detail sprite materials:
[[Image:detail shape tri.jpg|thumb|200px|left|Detail shape of "tri"]]
[[Image:detail shape cross.jpg|thumb|200px|right|Another "tri" with a small distance value]]
{|
! Detail Shape || Comment
|-
| <code>cross "cross"</code> || This makes a criss-cross shape.
<br>
Places two sprites which cross over one-another in the middle.
|-
| <code>triangle "tri"</code> || This makes a detail in the exploded prism shape .
<br>
Places three sprites sitting equidistant from each other in a triangle formation.
|}
<br style="clear:both;">


==Refining Detail Shapes==
* 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...''.


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).
{{bug|hidetested=1|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.
! Property || Comment
|-
| <code>"sway"</code> || Percentage of ''cl_detail_max_sway'' ( default 5 ).
<br>
'''Value''': 0.0 => 1.0
|-
| <code>"shape_angle"</code> || ''Specific to "tri" shape''. Degrees to angle out each of the leaves.
<br>
'''Value''': 0 => 90 (Untested)
|-
| <code>"shape_size"</code> || ''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.
<br>
'''Value''': 0, 1 (Untested)
|}


==Related Console Commands==
== Utilities ==


There are several clientside [[console]] commands you may use to alter the behavior of detail sprites.
{{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]].
! Command || Comment
[[Category:Level Design]]
|-
| <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.
|}

Latest revision as of 11:06, 23 September 2025

English (en)Русский (ru)Translate (Translate)
Broom icon.png
This article or section needs to be updated to include current information regarding the subject.
Remember to check for any notes left by the tagger at this article's talk page.
Detail props create the foliage in this screenshot from Dear Esther 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 cheap, non-solid objects that randomly emit from materials used by brushes and displacements. They fade out at a distance (by default 1200 units, or 4096 in Half-Life 2 20th anniversary and Portal May 2025 update), 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 (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.
Confirm:Verify if true:
Icon-Bug.pngBug:In the vanilla shaders, only the first group defined in the .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.
Cpp.pngCode:Stock compilers limit the number of detail props to 65535. This is not an engine limit, and can technically be raised if necessary by modifying a sanity check in AddDetailSpriteToLump from 🖿utils/vbsp/detailobjects.cpp. Raising it too high can cause performance issues, however.
Warning.pngWarning:Left 4 Dead 2 has mutually exclusive detail props. You may not be able to mix nature materials because it would show broken detail props. See L4D2 Detail props for more info.

Usage

Types of detail prop cover ("detail types") are defined in a .vbsp script file (in ANSI format).

Detail props are referenced in materials (VMT file) with the %detailtype parameter (e.g. "%detailtype" "grass01").

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.pngTip: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 (below).

Stock detail types

These types are available in Source SDK Base
Type View
swamp_land_002
grass01 Grass01.jpg
grass02 Grass02.jpg
coastline_grass01 Coastline grass01.jpg
coastline_grass02 Coastline grass02.jpg
coastline_redgrass01 Coastline redgrass01.jpg
coastline_redgrass02 Coastline redgrass02.jpg
coastline_redgrass03 Coastline redgrass03.jpg
citygrass01 Citygrass01.jpg
redgrass Redgrass.jpg
redgrass_light Redgrass light.jpg
short_redgrass Short redgrass.jpg
canal_reeds Canal reeds.jpg
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 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.pngTip: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.pngNote: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.pngTip:By setting a high minangle you can target overhangs. 0 is a flat surface, 90 is straight up.

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.
    Icon-Bug.pngBug: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.
Note.pngNote:In Counter-Strike: Global Offensive, sprites seem to always use 2, ignoring what is set in the vbsp.
Note.pngNote: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.pngNote:The sprite is rendered inverted in the X-axis

Shapes

sprite_shape tri
sprite_shape cross

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.pngNote:Counter-Strike: Global Offensive sprite shapes work with UnlitGeneric and LightmappedGeneric, but not the grass shader
Warning.pngWarning: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.)
Icon-Bug.pngBug: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.pngNote:Detail shapes are only available in some games, such as Day of Defeat: SourceCounter-Strike: SourceCounter-Strike: Global OffensiveGarry's Mod 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.pngTip: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.pngTip:The prop doesn'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!

Warning.pngWarning:Keep a very low amount of models even if in game performance is alright. They will make the game/mod crash upon 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.

model <string>
A model to use; must be $staticprop and UnlitGeneric (ALL skins). Include \models and .mdl in the path.
Cpp.pngCode: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:

Note.pngNote:Detail sprite shapes will suffer from alpha sorting issues if using $translucent. $allowalphatocoverage is not supported for detail sprites.
  • Unless you are overwriting detail\detailsprites.vmt, mappers must remember to select the correct material in Map > Map Properties....
Icon-Bug.pngBug: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.

Blocking detail props

If you do not want to have detail props being generated in a specific area, use func_detail_blocker (in all games since Left 4 Dead)(also in Garry's Mod). If func_detail_blocker is not available in the target game, a duplicate VMT of the material could be made without the %detailtype parameter.

Utilities

XBLAH's Modding Tool XBLAH's Modding Tool

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

Retrieved from "https://developer.valvesoftware.com/w/index.php?title=Detail_props&oldid=489043"