func_detail is an internal brush entity available in all Source games. It creates a brush that does not affect visibility or cause other brushes to be chopped. All brushwork that does not form the 'backbone' of the world (and that is not tied to a real entity) should be detail.
Valve provides an example map at
sourcesdk_content\hl2\mapsrc\sdk_func_detail.vmf. You can also load up the HL2 map sources and hide detail brushes with their auto visgroup to see where Valve used them.
r_drawfuncdetailto hide detail brushes in any map while it is running.
The point of creating a detail brush entity is to avoid creating an unnecessary number of visleaves for a mere detail of the map, hence the name of the entity. VBSP will allow visleaves to overlay details, and thus minimize visleaves and compile time.
Above are a world brush (left cylinder) and a detail brush (right cylinder). The blue lines are visleaf boundaries. The world brush has chopped the map into nine oddly-shaped segments, leading to longer compile times and marginally lower performance, while the detail brush has not changed anything.
- Detail brushes cannot be used to seal a map, or areaportal areas.
- Because detail brushes do not chop world brushes, light can seep underneath them if the other surface's lightmap scale is larger than the detail brush is wide/tall. If you encounter this, manually slice the underlying brush in two (with + ).
- This effect can cause detail brushes with lots of surface contact to become inefficient, because the surface beneath them is being rendered too!
- Detail brushes do chop each other, however.
- Surfaces on very thin (about 2 units thick) detail brushes have been known to disappear at certain distances. As a workaround, use func_brush instead.
- World brushes with translucent materials applied, or which are displacements, will be treated as detail, and cannot seal areas.
- World brushes w/ translucent material will still chop leaves, but to no effect.
- Detail brushes will, in some cases, merge faces with other detail brushes, and on occasion, world brushes, which can cause them to create leaves.
- Under normal conditions, any time a detail brush contacts a world brush, VBSP will note the junction and optimize it. This connection is known alternately as a T-junction and a water index, and there is a limit to the number of T-Junctions VBSP will attempt to fix (65,535). Excessive use of detail brushes in contact with world geometry could cause VBSP to abort compilation with an error. Using the
-notjuncoption will skip this optimization at the price of possible visual inconsistencies.
Any brush which doesn't significantly block the player's view should probably be detail. Specific examples include:
- Pillars, plinths and supports
- Free-standing walls
- Suspended walkways
- Steps (create a smooth wedge-shaped world brush underneath)
- Small buildings
- Rotated brushes
- Very small or thin brushes
- Brushes in the 3D skybox. (Excluding displacements)
- Minimum DX Level (mindxlevel)
- The entity will not exist if the engine is running outside the given range of DirectX Versions. Replaced by SystemLevelChoice from Left 4 Dead onwards.
- Warning: If these are used, the object may break when the user switches their DirectX settings.
- Maximum DX Level (maxdxlevel)