Brush entities are one of the two types of
entity. A brush entity is comprised of one or more
brushes, and thus are entities that either define an area or make up some part of the level geometry. This includes doors, elevators, trains, buttons and more, as well as areas that trigger some element of game logic, such as causing damage to the player or activating other entities when the player enters them.
Properties
Brush entities have a few properties of interest that are only defined geometrically (not through entity keyvalues):
- The origin defines the center of rotation of some entities. Also the center of targeting entities like
env_beam
, and entity effects. Defaulting to the world origin (0 0 0), it can be configured by including the origin brush.
-
BOUNDINGBOX
The bounding box describes a cuboid that contains all solid geometry of the entity. It is used for visibility determination, the center of movement for func_trains
, the solid part of func_pushable
, and the total volume entities like func_button
or func_door
translates to when opening (the lip is subtracted from this). Likewise can be customized with the BOUNDINGBOX brush.
- Clip hulls, which defines collision. If removed via
zhlt_noclip
keyvalue, players will not collide with it in any way, and this effect is not limited to func_illusionary
. Brush triggers without clip hulls will not work for the respective hulls that are missing. Conversely, clip hulls can be added [back] with CLIP brushes or its respective hull-specific variants. zhlt_noclip
+ CLIP brushes is a useful strategy to simplify clipnodes on otherwise very detailed brushwork.
Some other properties applicable to brush entities in common (via various means):
- Render FX/Mode/Amount/Color - Sets how entities would render in game. Not applicable to triggers. Unique to scrolling textures, FX Color encodes their scroll speed.
- Entity Effects (effects) - Another, seldom-documented effect property that mostly emits light or other effects from the entity's origin.
- Contents (skin) - Describes the content of the volume inside the entity. Mostly only relevant to
func_water
, but also applicable to most brush entities, unless they enforce a specific content in their code (e.g. func_ladder
) or hijacked for other uses (e.g. func_pushable
).
Compiler keyvalues with no effect on entity's function:
- Light Origin Target (light_origin) - Make entity receive lighting from the position of the targeted entity. An origin brush is needed.
- Minimum light level (_minlight)
- ZHLT Lightflags (zhlt_lightflags)
- zhlt_customshadow - Controls custom shadow opacity/tint cast from entities that has Opaque set in the above attribute.
- zhlt_usemodel - Reuse the same brush model (and its hulls) as the targeted entity. This saves 1 brush model slot (of 512) for every use. Be aware that shared brush models share lighting and decals.
- zhlt_invisible - Makes the entity completely invisible.
- zhlt_embedlightmap - Bakes the lightmap onto the textures of individual faces to get around the missing lightmap in some Render Modes.
- zhlt_embedlightmapresolution - Controls the resolution of the above embedded lightmap textures.
💡 If you want, you can edit your
FGDs to expose the common properties above to all brush entities. One easy way is to extend the ZHLT BaseClass since most brush entities inherit it in most FGDs.
Advanced property: model
During compilation, the brushwork of entities are compiled into brush models (there can be 512 of these) and the raw brushwork data removed. In return, the entities get assigned a
model
keyvalue which points to the index into the
BSP file's brush model list. Multiple entities sharing this value will share the same brush model and this can be set up with the
zhlt_usemodel
keyvalue. It can even point to an external BSP file e.g.
models/healthbox.bsp
or an actual
model e.g.
models/prop/door.mdl
(Note: models use different kind of collision and thus absent if used like this. Also, the incompatible collision mode will crash the game when it checks for it.)
There doesn't seem to be a way to explicitly set
model
value in the editor short of redefining the FGDs, and such edits are usually done with post-compile tools like bspguy.
Types and interactivity
As previously mentioned way at the beginning of this page, brush entities can be cleanly divided into two types:
- Functional - entities that represents something e.g. doors, trains...
- Triggers - defining a volume that does things when you "touch" it.
These entities employ different types of interactivity (
monospaced
word being the name of the method used in code):
- Triggers primarily sense
Touch
, and binds that sense to its functionality, like administering damage, changing a player's friction, etc.
- Functional entities mostly use the
Use
functionality – coming from both players pressing USE key on it and from being triggered by other entities – which does things.
- Some functional entities can inflict damage when they get
Blocked
.
- A few entities only define an area of effect for other entities e.g.
trigger_transition
for trigger_changelevel
, and func_traincontrols
for func_tracktrain
, and does nothing on its own.
A
func_door
uses the first three.
For entities that define an area of effect, only the bounding box of the entity is used, so it should only be of cuboid shape to truthfully represent in-game behaviour. In the same vein, a
func_plat
creates its own trigger area that uses its bounding box as base, and likewise might work weirdly if allowed its default behaviour while being non-rectangular in shape. Last and most notably,
func_pushable
uses its bounding box for collision with players and not the clipping generated from its brushwork.
Miscellaneous