> For the complete documentation index, see [llms.txt](https://book.leveldesignbook.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://book.leveldesignbook.com/appendix/tools/trenchbroom.md).

# TrenchBroom

[**TrenchBroom**](https://kristianduske.com/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.

{% embed url="<https://www.youtube.com/watch?v=shcAvnYp9ow>" %}

## Workflow

TB departs from previous Quake-era level editors to emphasize 3D construction in a single view pane.&#x20;

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](/process/blockout.md), but it also allows surprisingly detailed modeling and texturing when [art passing](/process/env-art.md).

{% columns %}
{% column width="50%" %}

<figure><img src="/files/-MGieDp2Fm8LbDvJ1WXD" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/-MGiXldb2hgrKJgePSxe" alt=""><figcaption></figcaption></figure>

*gallery of various TB construction and texturing demos, from* [*"Bal's Quake Mapping Tips & Tricks"*](https://www.slipseer.com/index.php?threads/bals-quake-mapping-tips-tricks.100/) *by Benoit "Bal" Stordeur*
{% endcolumn %}

{% column width="50%" %}

<figure><img src="/files/-MGieUxayXworeJoVm69" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/lQBpBbnnL7Zl7HpTpTJ6" alt=""><figcaption></figcaption></figure>
{% endcolumn %}
{% endcolumns %}

## Is TrenchBroom good for my non-Quake project?

If it's not a Quake mod, there are several aspects to consider:

* **.MAP / .BSP support**: can your engine import or compile [.MAP files](/appendix/resources/formats/map.md) or .BSP files?
  * TB's main file format is text-based **Quake .MAP**, Valve variant ("version 220")
  * If it's not a Quake engine, you'll need a plugin to import .MAPs or compiled .BSPs
  * Worst case scenario: export brushes to .OBJ but lose all entity data
* **Asset integration:** can TB hook into your game assets?
  * TB can read **common file formats** like PNG, JPG, FBX, OBJ, etc
  * Some plugins can **sync to Quake formats**, e.g. texture bundles like .WAD
* **Scripting:** how complex are your scripting needs?
  * To place game objects or do scripting, TB gets **entity definitions** in [**.FGD**](/appendix/resources/formats/fgd.md) files.
  * TB is OK for simple Quake-style scripting: placing objects, linking buttons to doors, or plotting simple paths... but it's a bit painful to script cutscenes or choreograph complex sequences.
  * Or maybe use TB only for 3D construction and markup, and do all your scripting natively in whatever game engine you're using.

## TrenchBroom engine compatibility / pipelines

<table><thead><tr><th width="147.423579283495">Game / Engine</th><th width="295">.MAP support</th><th>Asset integration</th></tr></thead><tbody><tr><td><strong>Godot</strong> </td><td>import via <a href="https://github.com/func-godot/func_godot_plugin">FuncGodot</a> (<a href="https://func-godot.github.io/func_godot_docs/FuncGodot%20Manual/FuncGodot%20Manual.html">docs</a>) or <a href="https://github.com/QodotPlugin/qodot-plugin"><del>Qodot</del></a> <del>(</del><a href="https://qodotplugin.github.io/"><del>docs</del></a><del>)</del> <em>(discontinued)</em></td><td>common file formats, FGD / WAD via plugin</td></tr><tr><td><strong>Unity</strong></td><td>import via <a href="https://assetstore.unity.com/packages/tools/level-design/tremble-map-importer-277805">Tremble</a>, <a href="https://github.com/chunky-cat/Qunity">Qunity</a>, <a href="https://github.com/radiatoryang/scopa">Scopa</a>, or <a href="https://github.com/wfowler1/Unity3D-BSP-Importer">Unity3D-BSP-Importer</a></td><td>common file formats, FGD / WAD via some plugins</td></tr><tr><td><strong>Unreal</strong></td><td>import via <a href="https://nte.itch.io/hammuer">HammUEr</a> (<a href="https://store.steampowered.com/news/app/1371690/view/2905347823300141067">guide</a>)</td><td>common file formats, textures via TextUEr (<a href="https://store.steampowered.com/news/app/1371690/view/2905347823300141067">guide</a>)</td></tr><tr><td>Quake 1</td><td>compile to BSP via <a href="https://github.com/ericwa/ericw-tools">EricW-tools</a></td><td>built-in FGD / WAD / MDL</td></tr><tr><td>Quake 2</td><td>compile to BSP via <a href="https://github.com/qbism/q2tools-220">q2tools-220</a></td><td>built-in FGD / WAL / MD2</td></tr><tr><td>Quake 3 (<a href="https://github.com/TrenchBroom/TrenchBroom/issues/2425">incomplete</a>)</td><td>compile to BSP via <a href="http://q3map2.robotrenegade.com/">q3map2</a></td><td>built-in MD3 / etc but no patch editing support yet (or ever?)</td></tr><tr><td>Half-Life (<a href="https://github.com/TrenchBroom/TrenchBroom/issues/1140">almost</a>)</td><td>compile to BSP via <a href="http://zhlt.info/">ZHLT v3.4+</a> / VHLT (<a href="https://twhl.info/wiki/page/Tutorial%3A_Setting_up_TrenchBroom_for_GoldSource_games#Setting_up_VHLT">guide</a>)</td><td>built-in FGD / WAD3 / MDL</td></tr><tr><td>Doom 3 (<a href="https://github.com/RobertBeckebans/TrenchBroomBFG">fork</a>)</td><td>via <a href="https://github.com/RobertBeckebans/TrenchBroomBFG">custom fork Trenchbroom-BFG</a></td><td>via <a href="https://github.com/RobertBeckebans/TrenchBroomBFG">custom fork Trenchbroom-BFG</a></td></tr></tbody></table>

* **If mapping for Quake**, ask for help at [**Quake Mapping Discord**](https://discord.com/invite/58XqmZM)
* **If using Godot, ask for help at** [**FuncGodot Discord**](https://discord.gg/eBQ7EfNZSZ)
* To build a .MAP file importer for any engine, see [MAP file format](/appendix/resources/formats/map.md) for info and example code
* For non-Quake engines, you must create a [TrenchBroom game configuration](https://trenchbroom.github.io/manual/latest/#game_configuration). See the [GitHub repo `/resources/games/` folder](https://github.com/TrenchBroom/TrenchBroom/tree/master/app/resources/games) to study example configs.
* Be advised, TB probably isn't the best tool for Quake 3 or Doom 3 engines. See [Tools](/appendix/tools.md) for a full list of game engines and recommended level editors.

## Resources and Community

* [TrenchBroom manual](https://trenchbroom.github.io/manual/latest/)
* [Download TrenchBroom on GitHub](https://github.com/TrenchBroom/TrenchBroom/releases)
* [TrenchBroom repo on GitHub](https://github.com/TrenchBroom/TrenchBroom)
* [TrenchBroom Discord](https://discord.gg/WGf9uve)
* [**Intro to TrenchBroom quickstart tutorial videos**](https://www.youtube.com/watch?v=gONePWocbqA) 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)**](https://www.slipseer.com/index.php?threads/bals-quake-mapping-tips-tricks.100/) 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 utility tools

* (Windows) [**OBJ2MAP**](https://bitbucket.org/khreathor/obj-2-map/wiki/Home) by Warren Marshall / Aleksander Marhall converts .OBJ 3D models to .MAP brushes. Be warned the tool is quite old, but it's useful for complex shapes, terrain, or reference geo.
  * NOTE: If you're using a modern game engine, just import the .OBJ directly, no need to use this tool. This utility is more for Quake / Half-Life mappers.
* (web) [**TrenchBroom Prefabs**](https://spacehare.github.io/prefabs/) by SpaceHare lets you copy and paste cylinders, arches, and staircase primitives into the editor.
* (web) [**func\_terrain**](https://tools.ummjackson.com/func_terrain) by Jackson Palmer lets you generate "triangle soup" style brush terrain with noise patterns or paint your own heightmap

<figure><img src="/files/BdmkaZE4keAQBOKf7iIE" alt=""><figcaption><p>screenshot of various copy-and-pastable TrenchBroom primitive prefabs, <a href="https://spacehare.github.io/prefabs">web tool by SpaceHare</a></p></figcaption></figure>