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

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

<figure><img src="https://1666186240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LtVT8pJjInrrHVCovzy%2F-MGiaafOL1SFz9zF9aNV%2F-MGieDp2Fm8LbDvJ1WXD%2FTrenchbroom_Bal_CreateVerts.gif?alt=media&#x26;token=d4b48e7b-24d3-4031-a6e5-0e5d2169c7bf" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1666186240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LtVT8pJjInrrHVCovzy%2F-MGiUfyjhNJ37SvNCFCm%2F-MGiXldb2hgrKJgePSxe%2FTrenchbroom_Bal_TorusConstruction.gif?alt=media&#x26;token=a57d7d13-796d-4b42-b861-fb904b9d9c03" 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="https://1666186240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LtVT8pJjInrrHVCovzy%2F-MGiaafOL1SFz9zF9aNV%2F-MGieUxayXworeJoVm69%2FTrenchbroom_Bal_TextureSkewValveFormat.gif?alt=media&#x26;token=7fee1851-ec8c-48e9-aa8a-3fe6e5588116" alt=""><figcaption></figcaption></figure>

<figure><img src="https://1666186240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtVT8pJjInrrHVCovzy%2Fuploads%2FJ1ZcTwaLnURdEyqdeLSB%2Fbal_tb_trenchbroom_curveTexturing.gif?alt=media&#x26;token=d1453e7d-a765-47cd-a572-92ef25db2d20" 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](https://book.leveldesignbook.com/appendix/resources/formats/map) 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**](https://book.leveldesignbook.com/appendix/resources/formats/fgd) 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](https://book.leveldesignbook.com/appendix/resources/formats/map) 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](https://book.leveldesignbook.com/appendix/tools) 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="https://1666186240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LtVT8pJjInrrHVCovzy%2Fuploads%2Fuys4OZ1YaobF90UDCIrz%2Fimage.png?alt=media&#x26;token=c608fcee-96e1-40bc-9566-1f3620e486d6" 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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://book.leveldesignbook.com/appendix/tools/trenchbroom.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.