VERC: Compiling 101 Last edited 5 years ago2019-04-19 08:37:10 UTC

One of the many initial pitfalls of mapping for new mappers is compiling. It can be very confusing if approached from the wrong angle, and is difficult to find good resources for. This is where this tutorial comes in.

---

What is compiling?

Compiling is simply the process of turning your Hammer map into something that can be read by Half-Life. As you probably already know, the file you modify in Hammer is an .rmf file. This file is specific to Hammer, and is just for that purpose. Half-Life, however, cannot read this file in-game. Half-Life can only read .bsp files, and this is what the compiling process creates.

---

How does compiling work?

First, your .rmf file must be exported to a .map file. This is simply a text file, that has all the information of your map. This file will be used for compiling, and not the .rmf file. Then, compiling is done in four separate steps: CSG, BSP, VIS, and RAD, and they must be performed in that order. CSG stands for Constructive Solid Geometry. This is the stage that creates the map's brushes, and then creates four hull files for BSP to use. The BSP stage actually creates the .bsp file, which is run by Half-Life. Next up is VIS, which is short for Visible Information Set. This generates what can and can't be seen from certain locations in the map. Half-Life will then use this information when running the game to help speed up rendering, by only drawing what the player can see. Finally, RAD is performed, which is short for Radiosity. This stage simply performs light calculations for the map.

For each of these steps is a separate program. The default programs that come with Hammer are commonly referred to as the "q-tools", and are qcsg.exe, qbsp2.exe, vis.exe, and qrad.exe, respectively. While these are okay, they are, however, are not recommended. The better tools to use are Zoner's Half-Life compile tools. They have been modified specifically for Half-Life use (rather than Quake) and are much more efficient. Further more, a local community member, Merl, modified Zoner's tools a bit more to add a few new, but imporant features. If you'd like to use this custom build of Zoner's tools, you can check it out here. The programs are, again respectively, hlcsg.exe, hlbsp.exe, hlvis.exe, and hlrad.exe.

Note: The above link to ZHLT has been removed, and the link to Merl's ZHLT Custom Build has been updated. There is no reason to use the older ZHLT version in place of Merl's updated ZHLT. -autolycus

Also, the RAD stage of compiling will need to reference a file called lights.rad. Make sure this file is in the same directory as your compile programs. This file has a list of all textures that emit light on their own, along with the color and brightness of the light. If this file is not in the correct directory, or does not have any contents, your texture lights in your map will not work. Keep in mind that the lights.rad file that comes with Hammer is initally empty - all of the actual contents are in the file called valve.rad. So, before your first compile, you must copy the contents of this file into lights.rad, and make sure lights.rad is in the same directory as your compile programs.

---

Parameters

Parameters are additional commands that can be added to the end of an .exe file, or in some cases, simply the direct object of any command. To put it simply, they alter how the .exe is run. All parameters for .exe files are proceeded by a space and a dash (-). For example, if I added the -dev and -console parameters to hl.exe, its path would look like this: C:\Sierra\Half-Life\hl.exe -dev -console. This would do two things (two parameters): 1) It would launch HL in dev (developer) mode, showing me helpful information and such in the console, and 2) It would launch HL with the console activated. Another popular parameter is -game (space) modname. This will automatically launch HL into the specified mod. For example, to have hl.exe automatically launch in TFC, you make it look like this: hl.exe -game tfc. Also, you can have the .exe file automatically perform certain console commands by using a plus (+) instead of a dash. For example, to automatically run HL with mymap, do this: hl.exe +map mymap. This is equivalent to opening HL, pulling down the console, and typing map mymap. There are many commands that can be added to the compile programs that greatly affect how they are ran. A list and explanation of these commands can be found ZHLTReference.html in your \zhlt directory. An example would be: vis.exe -fast.

Also, in the case of simple commands (such as copy, paste, etc.), a "parameter" would simply be the direct object of this command, usually a file. For instance:

copy mymap.bsp
command     parameter

As you will see, that last part will come more in handy later.

---

How do I use these programs to compile my map?

There are three different methods to use these programs to compile your map. You can either 1) do it from Hammer itself, 2) use a front-end GUI, or 3) use a batch file. I will now explain these three methods, along with their advantages and disadvantages.

---

1) The first and easiest method is to do it from Hammer itself. To set it up, you must first correctly set up all of Hammer's options that pertain to compiling. You can see the Options dialog in Hammer by going to the Tools menu, and then clicking on Options... at the bottom.

Once here, go to the Game Configurations tab, and set it up like so (I will only discuss the fields that pertain to compiling, other things must be set up as well for general mapping and Hammer use):

• Game Executable Directory - Set this to the directory at which you installed Half-Life (the default is C:\Sierra\Half-Life).
• Mod Directory - Set this to the directory of the mod on which you are working. For default Half-Life, leave this blank. For TFC, for example, the default would be C:\Sierra\Half-Life\tfc.
• Game Directory - Set this to the valve directory within the Half-Life directory. The default path would be C:\Sierra\Half-Life\valve.

After you've done all that, go to the Build Programs tab, and set it up according to the following:

• Game Executable - Specify the game executable here. The default would be C:\Sierra\Half-Life\hl.exe. For retail CS, it would be C:\Sierra\Counter-Strike\cstrike.exe.
• CSG, BSP, VIS, and RAD executables - Here, specify all of your compile programs, respectively. For example, for CSG, it could be C:\Program Files\Valve Hammer Editor\tools\zhlt\hlcsg.exe, or something like that. The path doesn't matter, just make sure it's the right program, and that all the programs are in the same directory.
• Place compiled maps in this directory before running the game: - This is where the final .bsp file will be copied to. You want this to be the \maps folder of whatever mod you're working on (remember, default Half-Life is the \valve directory). For example, if you're making a TFC map, it could be C:\Sierra\Half-Life\tfc\maps. For HLDM (standard HL), it could be C:\Sierra\Half-Life\valve\maps.

After this is all set up, you have two choices to compile from Hammer: Normal compile or Expert compile. To access either of these, when you're ready to compile, in Hammer, press F9. I will now explain the differences between Normal and Expert compile.

Normal compile will simply run each of the four programs. It gives you a few different parameter options for them, two other choices in checkbox style, and allows you to enter parameters for hl.exe. The two choices are as follows:

• Don't run the game - This will keep Hammer from automatically launching Half-Life after compiling is finished. If this is not checked, Half-Life WILL automatically launch after compiling is finished.
• Save visible objects only - This will only save currently visible objects to the .map file, which means in turn that only visible objects will be compiled. So say for example you had a few desks and small details you didn't want to compile to save time. Simply hide them, and run Normal compile, making sure to check this option.

Once you have things set how you want them, click OK. The .map file will automatically be written and compiling will commence.

This is just fine for a lot of compiles, however a lot of the time you will want more control over the parameters of the programs, along with other tasks you might want to add to the compile process (such as automatically deleting unneeded files at the end of the process). In this case, you will want to use Expert compile. To access it, hit the Expert button in the bottom-left of the Normal compile dialog.

Expert compile lets you individually add each step of the compile process. The dialog may seem confusing at first, but once you get used to its set-up, it shouldn't be that hard to grasp. To make things a lot easier and less time-consuming, start out with one of the pre-made ones, either default Half-Life, CS, OpFor, or TFC. These can be selected in the Configurations drop-down box in the upper left. As you can see, the compile/run commands are listed on the left. If you don't want to run a particular command that time, simply uncheck its checkbox. To add, remove, or move the position of a step, use the corresponding buttons in the middle. "Run with visible objects only" does the equivalent to "Save visible objects only" in Normal compile. So now, allow me to explain how the steps are written, and how commands and parameters are laid out.

Each step comprises of a command and a parmeter for that command, and sometimes even more parameters for that parameter. Anytime you enter a parameter from Hammer's expert compile, rather than putting what the actual parameter is, you will see a dollar sign ($) followed by something else, such as "gamedir" or "file". Hammer will get the necessary information to replace these parts from what you entered in the Options dialog above. To select a command for a step, highlight the step, and click the Cmds button on the right. Choose one of the following in the list that appears:

• Executable - This will open a browse window to let you choose an .exe file to run. You can then add any parameters you want to the .exe file.
• Change Directory - This lets you change the active directory. Having a directory "active" allows you to not type the whole path of a file. If it's in the active directory, simply the filename will do. Specify which directory to change to with a parameter.
• Copy File - This lets you copy a file. Specify which file with a parameter.
• Delete File - This lets you delete a file. Specify, once again, with a parameter.
• Rename File - This lets you rename an existing file. This requires two parameters - one for the file as it is named at the current time, and another for what you want the file to be renamed to.
• CSG, BSP, VIS, and LIGHT programs - These are your compile programs, csg, bsp, vis, and rad, respectively.
• Game program - This is hl.exe (or, in retail CS, cstrike.exe).

After you have chosen a command, you must specify one or more parameters for that command. Highlight the appropriate step, and hit the Parms button. Once again, choose one of the following:

• Map Filename (no extension) - This inserts the file name of the map you're currently working on as a parameter, without the extension.
• Map Filename (with extension) - Same as above, only with the extension.
• Map Path (no filename) - This will insert the path of the file, but without the map itself.
• Game Executable Directory - This will enter the directory where hl.exe resides as a parameter.
• BSP Directory - This will enter the directory where you specified to place compiled maps in the Build Programs tab in Hammer's Options dialog as a parameter.
• Game Directory - This will enter what you specified as the game directory in the Game Configurations tab of Hammer's Options dialog as a parameter (for example, C:\Sierra\Half-Life\valve).
• Mod Directory - This will enter what you specified as the mod directory in the Game Configurations tab of Hammer's Options dialog (for example, C:\Sierra\Half-Life\tfc).

Now that you have read and (hopefully) understood all of that, you should be able to understand what's going on in the compile/run commands list a bit better, and maybe add your own lines or modify existing ones. As you can see, the first step (of the Half-Life (full) setup) is to change the active directory to the game executable directory. As you should know, this was first done by selecting Change Directory from the Cmds menu as a command, and then Game Executable Directory from the Parms menu as a parameter. The next four commands are the four compile programs, with one parameter each - the path and name of the map to be compiled (Hammer will fill in the $path and $file you see there itself). If you want to add more parameters to these programs, you can easily do so by adding (space) -parametername after the $path\$file part. For example, you could do $vis_exe $path\$file -fast.

Next are two copy commands. Each one has two parameters: the path and file to be copied, and the directory to which to copy it. Let's take the first one as an example. After your map is compiled, the .bsp file will first be in your Hammer\maps folder. However, you want this file to be in your mod's \maps folder (or the valve\maps folder). So, it must be copied to that location. $path\$file.bsp takes your map's path and your map's name and tacks on .bsp as an extension, and copies that file to the $bspdir (place to put compiled maps) as a file called $file.bsp ($file will be replaced with your map's name). To put it simply, it's taking the .bsp file from the Hammer\maps folder and moving it to the mod's \maps folder. It also does this with the .pts file (for finding leaks). If you wanted to then get rid of these files from their original locations after the copy, you can add two Delete File commands. As parameters, enter Map Filename (no extension) for both. This will put in $file, which will be replaced with your map's name. Then, after the $file part, manually type each extension to be deleted, in this case .bsp and .pts. We can do this because, once they're copied to the other directory, they're no longer needed in their original location. So, the line would look like: Delete File $file.bsp/pts. Of course, this is purely optional. The last command is $game_exe (Game program from the Cmds menu), which will run hl.exe. It also has the -dev and -console parameters, along with the console command map $file. $file will be replaced with your map's name, so that HL will automatically launch the map you're compiling.

I know this probably all seems very confusing right now, but if you look over it a few times, and check out what it all does, it should become clear pretty quickly. Just remember the basics: You have a series of commands. Each one comprises of a command and a parameter(s). You must run each of the four compile programs, with your map name as a parameter for each, followed by two copy commands. The run game command is optional. Feel free to add delete/rename/copy commands as much you like to organize the files in a nice, automated process. Once you get it all how you want it, just click Go!, and compiling will commence.

Remember before when I said this was the easiest way? Right now you may be thinking "Of course not, this way is hard!" However, it really isn't, because once you get it set up how you like it, which may be the default anyway, all compiling involves doing is hitting F9, and clicking Go! Nice and simple. The explanation was lengthy, however, because I explained to you what each of the steps actually mean and how to customize them. This should make explaining the next two methods very simple.

---

2) The second method to compile is to use a front-end GUI. This is basically a program with a visual interface that does the same thing as Hammer's Expert compile does. Why use one, you ask? For two reasons: 1) You can close Hammer while compiling, freeing up system resources, which should speed up compiling time, and 2) If you get a good program (such as Nemesis' Batch Compiler) you'll have many nice options available to you, such as checkboxes for all compile parameters, the ability to save configurations, etc. Simply download one, install it, set it up, and compile! However, make sure you export your .rmf file to a .map file from Hammer (File->Export to .MAP) first. Remember, the compile tools use the .map file and not the .rmf file. The reason we didn't have to do this when compiling from Hammer was because Hammer did it for us automatically before compiling.

---

3) The last method to compile is to use a batch file. A batch file is simply a text document with DOS commands in it, renamed to whatever.bat. Then, when ran, it will automatically run all of the commands within it. As you can see, batch files can be very useful for performing a lot of tasks at once, in our case compiling. To use a batch file, you can either download one, or write your own. If you want to write your own, however, it is very simple. Simply take all of the standard commands, and write them out in a text file, very similar to Hammer's Expert compile. Then, when it's all written, rename it to whatever.bat, and double-click it whenever you want to compile (make sure to export to .map first). Here is a sample batch file that I wrote:

cd c:\worldcraft\tools\zhlt     this changes the active directory to where my compile programs are stored
hlcsg c:\worldcraft\maps\lun1.map     this runs hlcsg (no extension required), with one parameter - my map
hlbsp c:\worldcraft\maps\lun1.map     same, only for hlbsp
hlvis c:\worldcraft\maps\lun1.map -fast     same, only for hlvis, with the added -fast parameter
hlrad c:\worldcraft\maps\lun1.map     same, only for hlrad
cd c:\worldcraft\maps     changes directory to C:\Worldcraft\maps
copy lun1.bsp c:\games\half-life\lunacy\maps     copies .bsp file to my mod's \maps directory
del lun1.bsp     all of these commands delete files in my \Worldcraft\maps directory that I don't need
del lun1.lin
del lun1.p0
del lun1.p1
del lun1.p2
del lun1.p3
del lun1.prt
del lun1.wic

---

During/After Compiling

Regardless of which method you use to compile, you should see what's going on in a little window during compile. Sometimes the information produced in this window can be helpful in solving problems. If you are having problems, look over it when it's finished to see if you find any errors. For a list of common errors and explanations, check out ZHLTProblems.html in your \zhlt directory. If you accidentally close the window, or want to look at it later on, there should be a file in your Hammer\maps directory entitled mapname.log. Open this in Notepad or a similar text editor, and you should see the contents of your compile process. If people at the VERC boards need to see this to help you diagnose a problem, simply copy and paste in into your post.

After compiling is complete, you should have the following files in your Hammer\maps directory (assuming you did not delete them from your compile process): mapname.rmf, .rmx., .map, .max, .bsp, .lin, .p0, .p1, .p2, .p3, .prt, .wic, .log, and .pts. The .rmf file and .map file (and their corresponding backups) were already there before compile. All the others were generated during compile, with the .bsp being the final output. Make sure the .bsp file is copied to your mod's \maps directory so that it can be run by Half-Life. Also make sure you copy the .pts file so that, if you have a leak, you can follow the dotted line in-game. After those two files have been copied, you can safely delete all files here except for the .log file, as that should be kept for future reference. You can either do these copy and delete commands manually or automatically through your compile process. Just make sure the .bsp and .pts get copied BEFORE they get deleted from the original location.

---

Well that's about it. I know this can be a lot to chew at first, but it's really not that bad once you get used to it. To summarize: You must export to .map if you're not going to use Hammer to compile. You then must run the four compile programs using one of the methods specified. Each program must have a parameter of your map path and name (.map, not .rmf), plus others if you wish. The .bsp and .pts files must then be copied, and all others can be deleted if you so desire.

Have fun compiling!