## Documentation - ZHLT 2.5.3 Custom Build 1.6

This is a custom build of Zoner's Half-Life Tools, version 2.5.3. Sean (aka "Zoner") is NOT responsible for the tools in this zip. The purpose of this document is to highlight the differences between the generic ZHLT 2.5.3 and this version, and also to serve as a usage manual.
Revised 03/06/`02 Anthony Moore
Thanks goes to the following individuals for their contribution, be it with suggestions, criticism or beta testing: Zipster, Merkaba, Laurie, Mazemaster, Who? Me?, hullu & the Natural Selection team
If you are unsure of anything in here, try posting in the forums at the Valve-ERC or RUST and get one of the regulars to give you a hand. As a last resort, you can also contact me via e-mail.
Earlier versions of these tools are available here.

Contents of this file:

- the null texture
- automatic wad detection
- clipnode economy mode
- sky diffuse colour
- texture wad configuration file
- info_compile_parameters map entity
- info_texlights map entity
- max vis distance

| the null texture

The NULL texture is one that is removed from the map during compilation, so that it wont exist when you play the compiled .bsp file in Half-Life. You should be able to apply it to any entity or any world brush.
The main point of this texture is to use it on faces that the player would under normal circumstances NEVER see, so that they won't add to the w_poly count and lower the fps (frames per second) rate. You can also use the SKY texture for this exact same purpose, although there have been recent debates about whether this is actually beneficial. While it does lower the w_poly counts, it apparently also lowers the fps rate, thereby defeating its original purpose.
If you wish to use the NULL texture, make sure that you extract zhlt.wad from this zip to some directory, and add it to your texture wad configuration in Worldcraft (goto Tools, Options... and click on the Textures tab, then click on Add).

| 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 gives you, the mapper, the potential 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.
If you wish to enable this feature, simply use the -wadautodetect flag in the csg commandline.

| clipnode economy mode

This 'mode' is on by default in HLCSG, and does not require any interaction from the user at all. You can remain blissfully ignorant of this feature if you so wish.
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.
In this build of the tools, CSG 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 it will strip them away from the level. This means that by default, your clipnode counts will be lower than normal. IT DOESN'T automatically mean that you will never see another MAX_MAP_CLIPNODES error in your life, it just means it's less likely to happen in the first place.
If you believe that this feature is causing you troubles, than you have the option of turning it off. To do so, simply add the -noclipeconomy flag to the HLCSG commandline.

| sky diffuse colour

Really horrible HLRAD hack by Adam Foster
It's a hack to HLRAD that allows a different colour for the diffuse light from a light_environment, more accurately mimicking real-world lighting (yellow sun, blue sky).
It uses a new key, '_diffuse_light', in the light_environment - this gives the colour and intensity of the diffuse lighting, ie light from the sky, not from the sun.
It should be fully backwards-compatible with older maps - if there's no '_diffuse_light' key, it uses the intensity from the standard '_light' key.
Hope somebody finds it useful...
- Adam Foster afoster@compsoc.man.ac.uk

| texture wad configuration file

Release Information
The texture wad configuration file, called wad.cfg should be extracted to the same directory as the compile tools, or your Half-Life directory.
Whats the purpose of this feature?
Say, you map for 3 mods: Counter-Strike, TFC, and normal Half-Life Single Player. All three of these mods use different wads. Say you wanted to work on your Counter-Strike map one day, and TFC the next: because Worldcraft does not store which wad files are in use for each game configuration, you would need to go into Worldcraft texture configuration, Add/Remove wad files from the list, and Restart Worldcraft. Bit of a pain, huh?
The idealistic solution to this would be to make it so that Worldcraft stores which wad files are in use for any given game configuration, but that's not as easy as it would first appear. autolycus of the Valve-ERC states that "This is one of the most requested things, so yes, we know about it. I've requested the feature several times. You can be assured, Mr. Speyrer knows that this would be a handy thing.".
The solution (for the meantime, ie. until the In-House Valve level editor is releaed...)
So, for the mean time, i have devised up this method to overcome the hassle of restarting Worldcraft. In the wad.cfg file, you can explicitly define what wads you want written into the .bsp file, regardless of what happens to be in Worldcraft, for any given game configuration. So, now, HLCSG will ignore the wads that you have configured in Worldcraft, and instead only write in the ones you specify.
The specific syntax for the file is the following:

> configuration_name
> {
> c:\path\to\wad\wad1.wad
> c:\path\to\wad\wad2.wad
> include c:\path\to\wad\wad3.wad
> }

Where:

- configuration_name is some sort of descriptive word. Examples: valve, cs, tfc etc...
- c:\path\to\wad\wadn.wad is the full path to a texture wad file. if you are unsure as to what this should be, take a look at the paths in the Textures tab in Worldcraft configuration.
- If a wad is prefixed by include, that wad will be automatically wadincluded into the .bsp file.
- There is no limit to the number of configurations, or the number of wads you can have per configuration.

All that remains now is for me to run hlcsg.exe with the parameter -wadconfig configuration_name.
Lets take an example. Say i wanted to create a configuration called 'my_wads'. It has 3 standard wadfiles in it: 'halflife.wad', 'liquids.wad' and 'xeno.wad', all of which can be found in the valve directory, because they all came with Half-Life. It also has a custom wad created by me called 'mywad.wad', which I want to compile into the .bsp file, which also happens to be in the valve directory. My configuration might look something like this:

> my_wads
> {
> C:\Sierra\Half-Life\valve\halflife.wad
> C:\Sierra\Half-Life\valve\liquids.wad
> C:\Sierra\Half-Life\valve\xeno.wad
> include C:\Sierra\Half-Life\valve\mywad.wad
> }

Now, when i run hlcsg.exe when i compile my map, i put -wadconfig my_wads in the command line.
If you really don't understand the wad.cfg file syntax, then don't worry. You don't have to use it. However, it does come with some example configurations already in it; just open it in notepad and see if you can get the hang of it, because it can be quite handy.

| info_compile_parameters

This is a simple little point-based entity that you can place in your map, from which you can select standard compile settings instead of using the command line switches.
If your .fgd file does not have this entity in it, you can add the following code to the end of your .fgd (compatible with all versions of Worldcraft):

    @PointClass size(-8 -8 0, 8 8 32) = info_compile_parameters : "Compile Options"
    [
        texdata(string) : "Texture Data Memory (in KB)" : "4096"
        estimate(choices) : "Estimate Compile Times?" : 0 =
        [
            0: "Yes"
            1: "No"
        ]
        bounce(integer) : "Number of radiosity bounces" : 0
        ambient(string) : "Ambient world light (0.0 to 1.0, R G B)" : "0 0 0"
        smooth(integer) : "Smoothing threshold (in degrees)" : 0
        dscale(integer) : "Direct Lighting Scale" : 1
        chop(integer) : "Chop Size" : 64
        texchop(integer) : "Texture Light Chop Size" : 32
        hullfile(string) : "Custom Hullfile"

        priority(choices) : "Priority Level" : 0 =
        [
            0 : "Normal"
            1 : "High"
            -1 : "Low"
        ]
        wadautodetect(choices) : "Wad Auto Detect" : 0 =
        [
            0 : "Off"
            1 : "On"
        ]
        wadconfig(string) : "Custom Wad Configuration" : ""
        verbose(choices) : "Verbose compile messages" : 0 =
        [
            0 : "Off"
            1 : "On"
        ]
        noclipeconomy(choices) : "Strip Uneeded Clipnodes?" : 1 =
        [
            1 : "Yes"
            0 : "No"
        ]

        spawnflags(flags) =
        [
            1 : "Run CSG" : 1
            2 : " No Clip" : 0
            4 : " Only Ents" : 0
            8 : " No Sky Clip" : 0
            32 : "Run BSP" : 1
            64 : " Leak Only" : 0
            128 : " No Clip" : 0
            256 : "Run VIS" : 1
            512 : " Fast " : 0
            2048 : "Run RAD" : 1
            4096 : " Sparse " : 0
            8192 : " Circus Mode" : 0
            16384 : " Extra Mode " : 0
        ]
    ]

| info_texlights map entity

The info_texlights entity can act as a replacement for a lights.rad file, in that it simply resides within the map as a point based entity. The usefulness of this is that each map can have its own unique ambient lighting applied to it, and those settings will travel with the map and not affect any other maps.
Usage of the entity is much like that of the multimanager. To add an entry, take smart-edit off in Worldcraft and add key value pairs in manually; the key should contain the name of the texture to apply lighting to, and the value a set of numbers representing the red green blue lumionsity(brightness) of the texture, just as you would in the lights.rad file.
Notes: The presence of this file will not override the lights.rad, both the values specified in this entity and the lights.rad file will be used by hlrad. Thanks goes out to Laurie Cheers from the Spirit of Half-Life mod for the idea behind this entity.
If your .fgd does not contain an info_texlights entity, then you can add this line of code to your .fgd yourself:

    @PointClass color(255 128 0) = info_texlights : "Texture Light Config" []

| max vis distance

Maximum Distance Visibility (MDV) is a new feature that prevents leafs beyond a certain distance from being rendered (or even sent to the renderer at all). In conjunction with fog, it can become the ultimate catalyst when building and compiling large maps, especially those with open areas. However, due to the nature of the calculations, not all leaves beyond a certain distance are guaranteed to be prevented from being rendered; but those that are within the maximum distance are gauranteed to be rendered.
To use this feature, include the -maxdistance # parameter with your HLVIS command line, where # is the maximum distance in units.
There is a small side effect when using the Maximum Distance feature. HLRAD relies heavily on the visibility matrix to speed up lighting operations. As such, a normal RAD of the map will result in ackward, "cut off" lighting. This problem is easily solved, however it requires that you use Adam Foster's special version of HLRAD, which accomodates for the MDV lighting problem. (ed. Note: The version of HLRAD included in this release is the aforementioned hlrad.) When you use the -maxdistance parameter, an extra file named .vdt that contains the real visibility matrix (i.e without any MDV performed) will be created. Adam's HLRAD will use this file to correctly light the map.
Skyler 'Zipster' York - (zipster89134@hotmail.com)

| this lovingly hand-crafted documentation is © copyright Tony "Merl" Moore 2002