TrenchBroom
info and resources for this modern brush-based level editor tool
TrenchBroom (or TrenchBroom 2, or TB) is a free open-source cross-platform 3D level editor with modernized Quake-style brush-based construction and ongoing updates / support. It is widely used across several modding communities as well as commercial projects.
We recommend TB as a decent general purpose 3D level editor tool that potentially works with multiple game engines on Windows, macOS, and Linux.
Construction
TB departs from previous Quake-era level editors to emphasize 3D construction in a single view pane.
Clipping planes can be 3D, and all brushes are automatically validated for convexity. TB is also great at resizing many brushes at once, with SketchUp-like handling of shared planes and contextual extrusion. For its construction capabilities alone, we recommend TB for building blockouts, but it also allows surprisingly detailed modeling and texturing when art passing.
Scripting
TB currently has only basic tools for scripting levels. It parses a .FGD file for entity definitions, and users can create and edit keyvalues to script gameplay, with some limited autocomplete and colorpicker support. This is suitable for simple Quake-style scripting with entity chains, but lacks the functionality of something like Hammer's extensive entity I/O system.
Outside of Quake modding, most users do their level scripting in the Unity / Unreal / Godot editor itself, and make minimal / no use of TB's entity support. But if you really want to implement custom entity support for your game, you must write your own .FGD file and create your own TrenchBroom game configuration.
Compatibility / engine pipeline
Is TrenchBroom a good choice for your game engine? Two aspects to consider:
.MAP / .BSP support: can your engine import or compile .MAP files or .BSP files?
TB's main file format is a Valve variant ("version 220") of text-based Quake .MAP format.
Your engine needs some sort of compile tool or plugin to process .MAP files.
Some plugins can import compiled .BSP files instead.
Worst case scenario -- export brushes to .OBJ but lose all entity data
Asset integration: can TB hook into your game assets and display them?
To place enemies, doors, or other scriptable game objects, TB uses .FGD file with special extensions.
TB uses Asset Importer (AssImp) to read a wide variety of common file formats, such as PNG, JPG, FBX, OBJ, etc.
| Game / Engine | .MAP support | Asset integration |
|---|---|---|
Godot | common file formats, FGD / WAD via plugin | |
Unity | import via Tremble, Qunity, Scopa, or Unity3D-BSP-Importer | common file formats, FGD / WAD via some plugins |
Unreal | common file formats, textures via TextUEr (guide) | |
Quake 1 | compile BSP via EricW-tools | built-in FGD / WAD / MDL |
Quake 2 | compile BSP via q2tools-220 | built-in FGD / WAL / MD2 |
Quake 3 (incomplete) | compile BSP via q3map2 | built-in MD3 / etc but no patch editing support yet (or ever?) |
Half-Life (almost complete) | compile BSP via ZHLT v3.4+ / VHLT (guide) | built-in FGD / WAD3 / MDL |
Doom 3 (incomplete) | see RBDoom3-BFG | needs custom fork |
To build a .MAP importer for other engines, see MAP file format for info and example code.
If mapping for Quake, ask for help at Quake Mapping Discord
If using Qodot, ask for help at Qodot Discord or ask at FuncGodot Discord
For specific help with TrenchBroom itself, visit the TrenchBroom Discord
see Tools for a full list of game engines and recommended level editors
Resources and Community
Intro to TrenchBroom quickstart tutorial videos by David "dumptruck_ds" Spell assumes you're mapping for Quake but the general setup process is similar for mapping for any engine.
Bal's Quake Mapping Tips & Tricks (2022) by Benoit "Bal" Stordeur is a crucial must-read for intermediate / advanced Trenchbroom construction techniques. Although Stordeur is working in Quake, his advice is applicable to using Trenchbroom for any game.
TrenchBroom Prefabs by SpaceHare lets you easily copy and paste common shapes like cylinders, arches, and staircase geometry from a webpage into the editor.
Last updated
