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
The NULL
texture is one that is removed from the
map during compilation, so that it won't exist when you play the
compiled .bsp file in Half-Life. You should be able to apply it
to any entity or world brush within your map.
The main point of this texture is to use it on faces that the
player would under normal circumstances never see, so that
those faces will not 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 count, 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 hlcsg
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, 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. However, 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.
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
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:
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 you use the -verbose flag (or even set Verbose Compile
Messages to On in the entity!), the tool will print out its usage
settings from the info_compile_parameters entity.
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" []
Pulsing/Flickering texlights
All texlights can now pulse and flicker, like normal light
entities can. To use this feature, set the 'style' value on the
brush entity with the light texture.
If your .fgd doesn't include style values, add the following code
to each entity that needs flickering texlights:
style(choices) : "Texlight style" : 0 = [ 0 : "Normal" 10: "Fluorescent flicker" 2 : "Slow, strong pulse" 11: "Slow pulse, noblack" 5 : "Gentle pulse" 1 : "Flicker A" 6 : "Flicker B" 3 : "Candle A" 7 : "Candle B" 8 : "Candle C" 4 : "Fast strobe" 9 : "Slow strobe" 12: "Underwater" ]
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 <mapname>.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