This article's documentation is for the "GoldSrc" engine. Click here for more information.


From Valve Developer Community
Jump to: navigation, search


HLCSG HLCSG is the command-line tool that constructive solid geometry calculations to the map, effectively breaking up complex brushes into simpler polygons, and makes 4 hull files for HLBSP to use. It replaces QCSG from the original compile tools.


-brushunion #

  • Threshold to warn about overlapping brushes. This option is a mapper debugging feature. The value passed in is a percentage (0 to 100) of overlap of two brushes before a warning is printed. Starting with a high value (95+) is a good idea, as going too low to start can print hundreds or thousands of messages. The brush numbers of the intersecting brushes and the percentage in which they intersect each other is displayed for each occurence. This option is off by default as it dramatically slows down HLCSG to do these calculations.

-cliptype value

  • Select the clip hull generation method. Choices are smallest, normalized, simple, precise or legacy (default). The ExpandBrush function of HLCSG has been reworked to fix 2 bad assumptions that led to "sticky" exterior corners in Half-Life maps. To use the new clip hull feature, use "-cliptype precise". If you want to same some clipnodes, you can use "-cliptype simple" which will shift player models a few units upward on sloped floors. If you want to use the new HLCSG for the speed improvement but want the old style clipping, use "-cliptype legacy". If you want to have the smallest possible number of clipnodes and don't mind some stickyness (not recommended), use "-cliptype smallest". "-cliptype normalized" uses bugfix 1 and skips bugfix 2 for people who don't want denormalized brushes.

-hullfile file

  • Load a custom hullfile. Loads a custom set of hulls for the collision hull generation. The file is composed of 3 lines of 3 whitespace delimited numbers. Each line is an X Y Z size of the bounding box it is for. Only specific mod authors and their mapping teams should ever worry about this feature.


  • Don't create clipping hull. Half-Life, like Quake1, has 4 hulls: 1 visual hull and 3 collision hulls. This option disables generation of the collision hulls for a small savings in compile time. Note that the world will not be solid at all (everything will fall into the void) with this option set.


  • Disables redundant clipnode stripping. Clipnodes are 'planes' that restrict the player movement. They are placed along the walls and floors of your level, so that they player cannot pass though them. However, like everything else in the Half-Life universe, they are limited, and will max out with compile errors if you end up using too many of them. HLCSG will analyse how the clipnodes are being used in your map. If it thinks that it can get away with not using clipnodes in any particular situation (such as in func_illusionaries which don't need clipnodes), then HLCSG will strip them away from the level. This means that by default, your clipnode counts will be lower than normal. This doesn't mean that you will never see another MAX_MAP_CLIPNODES error, it just means it's less likely to happen in the first place. Use this switch to turn of clipnode economy mode if you believe that it is causing problems.


  • Disables NULL texture stripping.


  • Disable automatic clipping of SKY brushes. By default HLCSG will CLIP all SKY brushes, as well as remove all non-sky faces on the 'inside' of a sky brush (which eases up vis time, and improves some time and memory usage in rad as well).


  • Include all used textures into bsp. This option is obsoleted by -wadinclude and is only left in to retain some backwards compatibility.

-nullfile file

  • Specify a file containing a list of entities to retexture with the NULL texture.


  • Do an entity update from .map to .bsp This option will take the entities from the .map file and update them into the .bsp file. For the most part, entities can only be edited. Adding or removing any can reorder the other entities which frequently breaks brush based entities, especially triggers.

-tiny #

  • Minimum brush face surface area before it is discarded. Tiny brush faces are outright removed. The current cut-off is 0.5 square units. It is dangerous to drop faces in this manner, as the BSP tree for the world can be unusable, or generate leaf portal errors or hall-of-mirrors vis errors.


  • Enable automatic wad detection. Automatic wad detection is a simple utility that will exclude any wadfiles from the bsp that aren't in use by the map. This enables you to add any assortment of wadfiles you wish, and yet only have those that are actually used by the map included in the .bsp file.

-wadcfgfile path

  • Manually specifies the path to the wad.cfg file. By default, the tools will look in the same directory and the Half-Life directory.

-wadconfig name

  • Use a custom wad configuration in the wad.cfg custom wad configuration file. Custom wad configurations are used to enable you to choose which .wad files you want written into the the .bsp file, regardless of what happens to be in your editor, for any given game configuration. So, now, HLCSG will ignore the wads that you have configured in your editor, and instead only write in the ones you specify.

-wadinclude file

  • Place textures used from wad specified into bsp. This option will cause csg to include used textures from the named wadfile into the bsp. It does partial name matching, is not case sensitive, and can also match directory names. If multiple includes need to be done, -wadinclude must be specified multiple times, once for each include. Only textures actually used in the map are included into the bsp.
Note.pngNote:🖿zhlt.wad is always wadincluded.

Shared options


  • Display bsp statitics. This option will cause the program to print out the bsp statistics right before it writes out the bsp. It is most handy to do -chart with HLRAD and HLVIS at the end of the compiles. The ripent program will alway display the chart.

-dev # Compile with developer message. Internal ZHLT debugging messages have been slowly added to the tools. This variable sets the 'level' to display. In order (starting with 0 and going up) : Off, Error, Warning, Info, Fluff, Spam, MegaSpam. Generally this option should never be used except at request, to diagnose a compile problem on an end-users machine.


  • Display estimated time during compile. This option replaces the 10...20... style progress indicators with a estimate bar with some estimated completion times, as well as the exact number of the current job and how many jobs there are to do. The three different times remaining factor in varying amounts of historical data to guess how much longer it will take to run. It is good for a ballpark figure, but frequently not much more accurate than that.

-lightdata #

  • Set custom lightdata maximum (MB). Higher values than the default (6MB) can cause performance issues. You should perform compatability testing before releasing maps if they're over the preset limit.

-low | -high

  • Run program an altered priority level. Setting the priority of the compile tools to -low is very handy, as you can multitask and do other things without really feeling the drain of the compile programs on the system, provided there is enough memory for the tools and the other programs you use.


  • Do not show tool configuration information. ZHLT 2.1 added a configuration display for each of the tools as they run, to display the current settings for all configurable options as well as their defaults. This sometimes causes problems with other programs, most notably when compiling within Worldcraft, it likes to crash when too much stuff scrolls into its compile process window.


  • Don't generate the compile logfiles. This option just disables the generation of the .log and .err files which are normally generated whenever the compile tools run.

-texdata #

  • Alter maximum texture memory limit (in KB). Half-Life was built with a 2MB texture limit, as was Opposing Force. The ZHLT default limit is 4MB. Even 4MB can be a bit much, when combined with model textures, skies, hud graphics, and more. This is especially true of people with older cards (Voodoo 1 and 2's, etc).

-threads #

  • Manually specify the number of threads to run. This option is generally only necessary on the non-windows versions of the tools, where there is not a standard way to detect the number of processors in the system and auto-set the value. It can be manually set on windows machines, primarily if you wish to use fewer threads than processors.


  • Compile with verbose messages. Many of the tools have 'minor warnings' and informative messages which are displayed when verbose mode is set. As the ZHLT 2.x series developed, many of the developer specific settings have been moved to developer messages, while the mapper-related messages remain as verbose messages.