func_occluder

func_occluder is a semi-internal brush entity available in all  Source games. It hides models that are entirely covered by it in the player's view, according to how it has been textured.

Class hierarchy
CFuncOccluder ↳CBaseEntity
func_occluder.cpp

Green boxes represent occluded props, red boxes unoccluded ones.

Unlike func_areaportal or other optimization tools, occluders perform visibility calculations at run-time. They do not cut visleaves, and they do not hide world geometry (world brushes, displacements, etc). Because of this, they are much less effective when directly compared to areaportals or good Hint brush placement for optimization, and should be used primarily when the former strategies are not possible or ineffective on their own.

Note: VBSP may display a warning saying Occluder "" straddles multiple areas. This is invalid!. This warning is mostly obsolete. Removed in VBSP and VBSP++.

Warning: As occluders are skipped if they're in a disconnected area, an occluder will, on rare occasion, appear to not work. Assuming it takes up the required percentage of the screen, this is either because it's considered to be outside the map (identified via setting map_noareas 1) or past a closed areaportal. This may manifest more often when merging lots of occluder brushes into one entity, and even more so when spread across separate areas of the map (for example, multi-stage payload maps in  TF2).

Bug:Occluders placed in an Instance will not work due to VBSP not transforming the brushes when collapsing. Fixed in VBSP++  [todo tested in ?]

Usage

Occluders are very useful in cases where you have reasonably large func_detail, prop, func_brush, or displacement walls. These walls do not cut visleaves, meaning they will not stop world brushes, other displacements, or other props from rendering behind them. If you cannot use areaportals or hint brushes, occluders will at least hide props.

Occluders can also be helpful if certain parts of your map do not allow for efficient visleaf cuts, such as cylindrical buildings with multiple doorways, or flat open spaces with some geometry that can still block player vision. An example of this would be  Left 4 Dead's c8m1_apartment. Large occluders are used on the floor of the survivor starting area to hide props on the floors and street below, as well as the alley walls after leaving apartments.

's c8m1_apartment using occluders to hide props below the starting area.

Texturing

The occlusion will only work if the player is looking at the side that has the toolsoccluder texture applied, any nodraw faces will not occlude. This means you could make, for example, a large func_occluder cube, apply nodraw to the entire thing, then apply the occluder texture to only two faces. Only those two sides will hide models when the player is facing them.

Note: Technically, any face of the func_occluder without SURF_NODRAW will occlude, but using toolsoccluder is strongly encouraged to avoid ambiguity. Some older maps will use toolstrigger instead; this usage is deprecated and discouraged, as it will break if VBSP is compiled with -nodrawtriggers or -xbox.

Debugging Commands

r_occlusion

Activate/deactivate the occlusion system.

r_visocclusion

Activate/deactivate wireframe rendering of what the occlusion system is doing.

r_occludeemaxarea

Prevents occlusion testing for entities that take up more than X% of the screen. 0 means use whatever the level said to use.

r_occluderminarea

Prevents occlusion testing for entities that take up less than X% of the screen. 0 means use whatever the level said to use.

r_occlusionspew

Activate/deactivates spew about what the occlusion system is doing.

r_occludermincount

At least this many occluders will be used, no matter how big they are.

Keyvalues

Name (targetname) <string>

The name that other entities refer to this entity by, via Inputs/Outputs or other keyvalues (e.g. parentname or target).
Also displayed in Hammer's 2D views and Entity Report.

See also: Generic Keyvalues, Inputs and Outputs available to all entities

Initial State (StartActive) <boolean>

Default Value: 1
If the entity starts inactive, use the Activate or Toggle inputs to turn it on.

• 0: Inactive
• 1: Active

Occluder Number (occludernumber) <integer> !FGD

Automatically inserted by VBSP to distinguish occluders; should not be handled manually.

Inputs

Activate

Deactivate

Toggle

Control the state of the occluder.

External links

• Visibility Optimization
• Wikipedia on Antiportals (another word for occluders)