This is a brief, step-by-step guide on how to set up TrenchBroom for GoldSrc games.

Before we start

This guide assumes you have already installed TrenchBroom and are a bit familiar with it.

If not, you may go to TrenchBroom releases on GitHub, scroll down a little bit and find a download for your platform/operating system.
Also, if you would like to learn how to use TrenchBroom in general, dumptruck_ds's tutorial videos as well as TrenchBroom's own manual are great resources.

If you are new to making maps in general, it is also a good idea to read up on other mapping guides:

• Introduction to mapping
• Diagnosing problems
• Tips for beginner mappers
• How to fix those leaks

Lastly, note that TrenchBroom does not yet offer full support for Half-Life. For instance, while it can load Half-Life textures, sprites and models, it doesn't have a file browser where you can conveniently pick a sprite or model, instead you have to type paths to them manually. This may change in future updates.

Settings

First, you should let TrenchBroom know where Half-Life is located. Without that information, it won't know where to look for game files.

1. Launch TrenchBroom and click New map... 2. Click Open preferences... and select Half-Life. 3. Set the Game Path to your Half-Life installation directory.

• Windows: this is the folder where hl.exe is located. By default, this is C:\Program Files (x86)\Steam\steamapps\common\Half-Life.
• Linux: this is the folder where hl.sh is located. By default, this is $HOME/.steam/steam/steamapps/common/Half-Life ($HOME is the environment variable that is the path to your personal Unix user folder which is usually /home/<Unix user>).

Click Apply and done! It is not necessary to configure an engine, since we won't launch the game from TrenchBroom.

FGD files

FGDs describe what entities the game can offer to the map editor. Different mods / games like Counter-Strike may offer different entity types. (bomb spots, func_vehicle etc.)

Navigate to the folder where the game configuration files are located. That'll be different depending on the platform:

• Windows: this is the folder where TrenchBroom.exe is located.
• macOS: TrenchBroom.app/Contents/Resources
• Linux: <prefix>/share/trenchbroom, where <prefix> is the installation prefix.

Then, inside that folder, navigate to games/Halflife. TrenchBroom comes with a basic Half-Life FGD, however we also need zhlt.fgd. Without it, we wouldn't have certain special entities like func_detail. Now, there is a problem. TrenchBroom cannot load multiple FGD files at once. For that, we'll create a combined FGD. Do the following:
1. Create a new file, call it anything you'd like, for example halflife_zhlt.fgd
2. Open it with your preferred text editor (Notepad, Notepad++, VSCode...)
3. Write the following text:

// Combined Half-Life and ZHLT FGD
@include "zhlt.fgd"
@include "HalfLife.fgd"

4. Lastly, open GameConfig.cfg, go to line 18, and change it as follows: This change will make TrenchBroom load halflife_zhlt.fgd by default, so you don't have to switch to it every time.

Just to make sure, here is how your FGD should look in the end:

Creating a new map

Once you've set that up, make sure that your Map Format is set to Valve. The Standard map format is actually the Quake map format and isn't recommended for GoldSrc. (in fact, even Quake mappers use the Valve format, since it has better texture projection capabilities, and some additional Features.) You will be greeted by TrenchBroom's default layout and an almost empty map. Take a moment to familiarize yourself with TrenchBroom's user interface. If you aren't mapping for Half-Life, you may select a game/mod folder in the Mods section in the bottom-right corner.

---

The next step is to load textures. Go to the Face tab in the upper-right corner.
Look at Texture Collections in the bottom-right corner, and click on the + icon. Browse to a WAD file (e.g. Half-Life/valve/halflife.wad) and open it. TrenchBroom will ask you if you want to build a relative path to the WAD, or use an absolute path. Prefer relative paths if they are in your game folder. If they are elsewhere, such as E:/GoldSrcMapping/textures/zhlt.wad, definitely use absolute paths.

---

Note that you will have to load WADs every time you create a new map.

Now, after you've made a little room and placed an info_player_start, move on to the next section!

Setting up the compile Tools (VHLT)

Unlike textures, this process is only done once, and it is perhaps the most tedious and confusing for newcomers. However, don't worry, it is fairly straightforward.

1. Go to Run -> Compile Map.... You will see a Compile window with empty compilation profiles.
2. Create a compilation profile by clicking on the + icon at the bottom of Profiles, you may name it however you like (e.g. "Default")
3. Set Working Directory to ${GAME_DIR_PATH}
4. Add the following compilation steps:

1. Export Map

• File Path: ${WORK_DIR_PATH}/${MODS[-1]}/maps/${MAP_BASE_NAME}.map
• This will export the map to the game's maps directory. It is not a bad idea to have your original map file separate from the exported one.

2. Run Tool

• Tool Path: <path to VHLT>/HL-CSG.exe
• Parameters: "${WORK_DIR_PATH}/${MODS[-1]}/maps/${MAP_BASE_NAME}.map" -nowadtextures -clipeconomy

3. Run Tool

• Tool Path: <path to VHLT>/HL-BSP.exe
• Parameters: "${WORK_DIR_PATH}/${MODS[-1]}/maps/${MAP_BASE_NAME}.map" -chart

4. Run Tool

• Tool Path: <path to VHLT>/HL-VIS.exe
• Parameters: "${WORK_DIR_PATH}/${MODS[-1]}/maps/${MAP_BASE_NAME}.map"

5. Run Tool

• Tool Path: <path to VHLT>/HL-RAD.exe
• Parameters: "${WORK_DIR_PATH}/${MODS[-1]}/maps/${MAP_BASE_NAME}.map" -chart

In the end, you should have something that looks like this: You may now press Compile.
What happens from this moment onward is essentially equivalent to launching the Command Prompt on Windows and doing this:

xcopy mymap.map "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/valve/maps"
"C:/VHLT/HL-CSG.exe" "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/valve/maps/mymap.map" -nowadtextures -clipeconomy
"C:/VHLT/HL-BSP.exe" "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/valve/maps/mymap.map" -chart
"C:/VHLT/HL-VIS.exe" "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/valve/maps/mymap.map"
"C:/VHLT/HL-RAD.exe" "C:/Program Files (x86)/Steam/steamapps/common/Half-Life/valve/maps/mymap.map" -chart

Here's a Linux equivalent:

cp mymap.map $HOME/.steam/steamapps/common/Half-Life/valve/maps
$HOME/VHLT/hlcsg $HOME/.steam/steamapps/common/Half-Life/valve/maps/mymap.map -nowadtextures -clipeconomy
$HOME/VHLT/hlbsp $HOME/.steam/steamapps/common/Half-Life/valve/maps/mymap.map -chart
$HOME/VHLT/hlvis $HOME/.steam/steamapps/common/Half-Life/valve/maps/mymap.map
$HOME/VHLT/hlrad $HOME/.steam/steamapps/common/Half-Life/valve/maps/mymap.map -chart

In the end, you should see something like this in the compile log:

Object names  Objects/Maxobjs  Memory / Maxmem  Fullness
------------  ---------------  ---------------  --------
models              1/512           64/32768    ( 0.2%)
planes             20/32768        400/655360   ( 0.1%)
vertexes           20/65535        240/786420   ( 0.0%)
nodes               6/32767        144/786408   ( 0.0%)
texinfos            4/32767        160/1310680  ( 0.0%)
faces              16/65535        320/1310700  ( 0.0%)
* worldfaces       16/32768          0/0        ( 0.0%)
clipnodes          18/32767        144/262136   ( 0.1%)
leaves              2/32760         56/917280   ( 0.0%)
* worldleaves       1/8192           0/0        ( 0.0%)
marksurfaces       16/65535         32/131070   ( 0.0%)
surfedges          68/512000       272/2048000  ( 0.0%)
edges              35/256000       140/1024000  ( 0.0%)
texdata          [variable]      67732/33554432 ( 0.2%)
lightdata        [variable]       7860/50331648 ( 0.0%)
visdata          [variable]          1/8388608  ( 0.0%)
entdata          [variable]        319/2097152  ( 0.0%)
* AllocBlock        1/64             0/0        ( 1.6%)
3 textures referenced
=== Total BSP file data space used: 77884 bytes ===
Wad files required to run the map: (None)
0.09 seconds elapsed
-----   END   hlrad -----

#### Finished with exit status 0

You should now be able to see a BSP file in Half-Life's maps folder. You may then launch Half-Life, open the console and execute map mymap, or whatever the filename of your map is.

(Optional) Tool paths as variables

You may want to create multiple compilation profiles for different tasks, such as a profile for recompiling only the entities on a map, for example, and typing in the full paths to the tools' executables in Run Tool every time might get annoying. Fortunately, it's possible to specify tool paths in the Preferences menu as variables.
Quake's built-in config has fields for setting tool paths, but Half-Life lacks these options by default. You have to add these fields manually: Now if you go to the Half-Life's entry in the Preferences menu, it will have a "Compilation Tools" section, similarly to the Quake entry. After setting the paths there, you may use ${csg}, ${bsp}, ${vis} and ${light} instead of <path to VHLT>/toolname.exe when creating a compile task.

(Optional) Overriding the game configuration files

So far, we've been customizing our configs and FGDs in the resources folder for the game, which the manual refers to as <ResourcePath> since its location varies between platforms. Thus, GameConfig.cfg and the FGDs we modified earlier are in currently in <ResourcePath>/games/Halflife.
This works just fine, but the manual cautions against doing so:

The folder <ResourcePath>/games contains a .cfg file for each supported game, and additional folders which can contain additional resources related to the game such as icons, palettes or entity definition files.
It is not recommended to change these builtin game configurations, as they will be overwritten when an update is installed. [emphasis added]

Well, where should we keep our configs then?

To modify the existing game configurations or to add new configurations, you can place them in the folder <UserDataPath>/games, where the value of <UserDataPath> is again platform dependent.

What the manual proposes is to override the configurations - TrenchBroom will automatically substitute files in <ResourcePath> for files in <UserDataPath>, if they have the same names.
But where is that folder? As stated, it depends on your platform:

• Windows: C:\Users\<username>\AppData\Roaming\TrenchBroom
• macOS: ~/Library/Application Support/TrenchBroom
• Linux: ~/.TrenchBroom

You can easily access <UserDataPath> by clicking the folder icon near the bottom-left corner of the Preferences menu. If you've followed the guide so far, all you have to do now is copy the files from <ResourcePath>/games/Halflife to <UserDataPath>/games/Halflife, and make any further changes you want over there.

Troubleshooting

Chances are, you may run into some problems while following this guide.

Problem: I can't see any entities!

Check TrenchBroom's console, chances are you may see error messages like this:

Failed to parse included file: At line 1753, column 222: Expected '[', but got ':' (raw data: ':') (line 1753)

If so, check your FGDs for things such as:

@SolidClass = worldspawn : "This is the world entity. Each map can only contain one, and it's automatically created for you." : "http://twhl.info/wiki.php?id=162"

and make sure to delete the rightmost part:

: "http://twhl.info/wiki.php?id=162"

The FGD format is not very standardized, each map editor adds its own extensions to it. TrenchBroom does not support J.A.C.K.'s extensions, which was used in this example. This makes it quite tedious to port a J.A.C.K. FGD to TrenchBroom.

Problem: I am getting "Finished with exit status 1"

This means the compile has failed. You are likely seeing something like this:

-----  BEGIN  hlrad -----
Command line: E:\Workfolders\Half-Life\VHLT-ADM-v35\ADM-RAD.exe "D:\Program Files (x86)\Steam\steamapps\common\Half-Life/valve/maps/twhl_tut_1.map" -chart
Arguments: "D:\Program Files (x86)\Steam\steamapps\common\Half-Life/valve/maps/twhl_tut_1.map" -chart -low
>> There was a problem compiling the map.
>> Check the file D:\Program Files (x86)\Steam\steamapps\common\Half-Life\valve\maps\twhl_tut_1.log for the cause.

-----   END   hlrad -----

Do not panic. Simply scroll all the way up, and read the compile log from the beginning. Have a look at Tutorial: Diagnosing Problems, or ask for help. Everything will be fine.

For this example, the error was:

Problem: Error: ::LoadLump() texture __TB_EMPTY not found!

This means you did not assign a texture to at least one face. You must make sure every surface has a texture, even if it won't be visible in-game.

Problem: Warning: LEAK in hull 0

For this one, refer to Tutorial: How to fix those leaks. TrenchBroom supports, as of lately, VHLT pointfiles, so you can easily locate leaks.