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

Versions

At the time of editing, TrenchBroom is currently at v2023.1, and the guide should work for most versions!

If you are using a newer version and this guide does not work, consider reporting it in the comments, or update the guide. TrenchBroom is in active development and things can change from time to time.

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:

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 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 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.

zhlt.fgd?

ZHLT stands for Zoner's Half-Life Tools, a set of map compilers from the early 2000s. It has been superseded by Vluzacn's Half-Life Tools, which you can find in our Tools and Resources section.

You will need VHLT in order to build your maps, so Half-Life can load them. Read more in Tutorial: Compiling Introduced.

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 17, and change it as follows:

Before:

"entities": {
    "definitions": [ "HalfLife.fgd" ],
    "defaultcolor": "0.6 0.6 0.6 1.0",
    "setDefaultProperties": true
},

After:

"entities": {
    "definitions": [ "halflife_zhlt.fgd" ],
    "defaultcolor": "0.6 0.6 0.6 1.0",
    "setDefaultProperties": true
},

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)

You will be greeted by TrenchBroom's default layout and an almost empty map.

Hello, brush!

Naming

Please do not put spaces in your map names, or any special characters, and avoid uppercase characters. mymap or my_map is standard, MyMap not so much, My map is just not going to load.

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 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:

1. Open GameConfig.cfg.
2. Add the following section at the end:

"compilationTools": [
    { "name": "csg"},
    { "name": "bsp"},
    { "name": "vis"},
    { "name": "light"}
]

It should look like this

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.

That wasn't here before!

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.

Your compilation profile may look like this

(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.

This one, right here

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.

But there is a catch!

If you've followed the steps in Setting up VHLT, you will find a games/Half-Life folder in your <UserDataPath>, with a file called CompilationProfiles.cfg in it.
At the time of writing, TrenchBroom relies on the game's name, an attribute in GameConfig.cfg (the same name displayed in the Preferences menu), to look up/create its corresponding folder in <UserDataPath>, which it does whenever the compilation profiles are modified.
Note that Halflife and Half-Life are different names. If, for example, you create a folder <UserDataPath>/games/Halflife to override <ResourcePath>/games/Halflife, and then save a new compilation/engine profile, TrenchBroom will create a new folder <UserDataPath>/games/Half-Life to store that file. It might work anyway, but you'll end up with both a Halflife and a Half-Life folder, and a different compilation config in each. Confusing? Yeah, it really is.
To fix this inconsistency, you'll have to make these three things match:

<ResourcePath>/games/<name of game>
<UserDataPath>/games/<name of game>
"name": "<name of game>" in GameConfig.cfg (line 3)

Finally, put all files in <UserDataPath>/games/<name of game>.

Note: this behavior has been recognized as a bug, and should get fixed in an upcoming version of TrenchBroom.
Another caveat of the config's name attribute is that characters which aren't allowed in folder names (like colons and question marks) cannot be used in it, as doing so makes the editor crash due to being unable to create the game's corresponding folder.

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.

de_dust3

Commented 3 months ago2024-07-28 22:31:34 UTC Comment #106272

As of version 2024.1 (released march 4th), they've changed how WADs are managed.

From the github release:

WAD files are now managed by clicking on the wad property of the worldspawn entity. Selecting this property will show a list of WAD files below the entity property table. Use the buttons below the list to manage the wad files.

Admer456

Commented 3 months ago2024-07-29 20:04:53 UTC Comment #106275

Oh right I should probably update that. A simple screenshot change + edit the relevant paragraph a little bit.

Wertyartiom

Commented 2 months ago2024-08-12 16:07:28 UTC Comment #106296

Nice tutorial

Tutorial: Setting up TrenchBroom for GoldSource games Last edited 3 months ago2024-07-28 22:10:43 UTC