Tutorial: Setting up TrenchBroom for GoldSource games Last edited 6 days ago2023-05-23 23:43:59 UTC

This is a brief, step-by-step guide on how to set up TrenchBroom for GoldSRC games.
At the time of editing, TrenchBroom is currently at v2023.1, and the guide should work for the next few 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.


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...
User posted image
2. Click Open preferences... and select Half-Life.
User posted image
3. Set Game Path to your Half-Life installation directory, i.e. the folder where hl.exe is located. For example: C:/Program Files (x86)/Steam/steamapps/common/Half-Life.

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 you installed TrenchBroom, then games/Halflife.
User posted image
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 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 18, and change it as follows:
"entities": {
    "definitions": [ "HalfLife.fgd" ],
    "defaultcolor": "0.6 0.6 0.6 1.0",
    "setDefaultProperties": true
"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:
User posted image

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)
User posted image
You will be greeted by TrenchBroom's default layout and an almost empty map.
Hello, brush!Hello, brush!
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 familiarise 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.
User posted image
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.
User posted image
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 2. Run Tool 3. Run Tool 4. Run Tool 5. Run Tool In the end, you should have something that looks like this:
User posted image
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
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.


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 messsages 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 standardised, 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.


You must log in to post a comment. You can login or register a new account.