TrenchBroom: a cross-platform level editor for Quake-engine games

What TrenchBroom solves, and who it is for

Quake-engine maps are built from convex brushes, not from meshes. A brush is defined by planes, and every later edit has to keep those planes consistent. That constraint is what makes a dedicated editor worth having: a general 3D modeller can move vertices freely, but it will happily produce a non-convex shape that the engine's compiler rejects or silently mis-renders. TrenchBroom is built around that constraint. The README describes "robust vertex editing with edge and face splitting and manipulating multiple vertices together", which is the part that matters when a brush stops being a simple box.

The audience is narrow and clearly stated. The project calls itself a "modern cross-platform level editor for Quake-engine based games", and the supported list is Quake in both Standard and Valve 220 file formats, Quake 2, Quake 3 (partial), Hexen 2, Daikatana, and a Generic target for custom engines. If you are building a map for one of those, the editor speaks your file format directly. If you are building a scene in Godot or Unity, it does not, and the related searches for those engines reflect a confusion the README does not create: TrenchBroom outputs Quake map files, and using them elsewhere means running them through a separate conversion step that the README never describes.

How the editor is put together

The repository is a C++ application built with CMake, and the top-level layout shows the split clearly: app/ holds the editor itself, lib/ holds supporting code, cmake/ holds build modules, and www/ holds site content. CI-linux.sh, CI-macos.sh and CI-windows.bat sit at the root, so the three platforms are built by scripts rather than by a single wrapper. The credits list names Qt for the interface, FreeType for fonts, FreeImage for image loading, TinyXML for XML parsing, Assimp for model import, Catch2 for tests, and Pandoc, which suggests documentation is generated as part of the build.

The editing model is what the feature list describes. Work happens in a 3D view plus up to three 2D views, which is the standard arrangement for brush work: the 2D views give you axis-aligned precision, the 3D view gives you the result. CSG operations (merge, subtract, intersect) act on selected brushes, and the clipping tool works with two or three points. Texture lock is applied across brush editing operations, so moving a brush does not slide its texture coordinates. Entities come from FGD and DEF files, which means the property list you see in the editor is defined by the game configuration rather than hard-coded, and entity links are drawn in the viewport. The issue browser scans the map and offers automatic quick fixes, and automatic backups run alongside unlimited undo.

Installing TrenchBroom and setting up a first map

The README does not give install commands. It points at two places: binary builds from the releases page, and BUILD.md for compiling. Downloading the build for your platform is the path most people take, and the releases page is where the README sends you.

If you compile instead, start from the repository root and read BUILD.md first, because it is the file the README defers to and it carries the platform-specific steps. The build is driven by CMake, and the CI scripts at the root show the shape of a working configuration:

cmake --version
cat BUILD.md

Once the editor is running, the first real task is choosing a game configuration, because that determines which entities and textures you can use. The manual at trenchbroom.github.io/manual/latest is the reference for this, and the README links it directly. Creating a map is then a matter of placing brushes in a 2D view and inspecting them in 3D.

For a custom engine, the Generic target exists precisely so you can supply your own game configuration rather than being limited to the shipped games. The README states that "more games can be supported with custom game configurations", which is the extension point to look at if your engine is Quake-derived but not on the list.

When a map is finished, the .obj export in the feature list is the route out to other tools. That is export only; the README does not describe importing .obj files back into a map.

The Quake 3 gap and other limits

The sharpest limitation is stated in the README itself: Quake 3 support is "partial, no patches or brush primitives yet". Quake 3 mapping depends on both of those. Patches are the curved surfaces used for arches and terrain, and brush primitives are how Quake 3 stores texture projection on a brush. A mapper working on a Quake 3 level will hit the ceiling quickly, and the README does not give a timeline for closing it. Treat Quake 3 as a target for simple geometry only, or use a different editor for that game.

A second boundary is the file format itself. TrenchBroom edits Quake maps. It is not a scene editor, it does not understand Godot scenes or Unity prefabs, and the README never claims otherwise. The related searches pairing TrenchBroom with those engines suggest people are looking for a bridge that the project does not document.

There is also a support question the README leaves open. The feature list is long, but there is no statement about which platform builds are tested for a given release, and no statement about backwards compatibility of map files across editor versions. If you keep a long-running project, that silence is worth noting before you upgrade.

TrenchBroom compared with Hammer and Jack

The two comparisons people search for are Hammer and Jack, and they differ from TrenchBroom in approach rather than in polish.

Hammer is Valve's own editor, tied to the Source engine and to Valve's toolchain. It is the natural choice if your target is a Source game, because the engine, the compiler and the editor come from the same place and the entity definitions ship with the tools. TrenchBroom takes the opposite position: it is engine-agnostic within the Quake family, driven by external FGD and DEF files and by game configurations you can add. That makes it portable across Quake, Quake 2, Hexen 2 and custom engines, at the cost of not being the first-party tool for any of them. If you map for Source, Hammer is the default and TrenchBroom is not competing there.

Jack is a Quake map editor in the same space. The practical difference is the editing model and the surrounding tooling. TrenchBroom's feature list emphasises the 3D viewport, CSG, a UV view, texture lock across operations, and an issue browser with automatic fixes. Which of the two fits you depends on which of those you actually lean on, and the honest answer is that you should open a map in both before deciding, because editor feel is not something a feature list settles.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-22. The most recent release is v2026.2 from 2026-08-21, preceded by two release candidates in July and August 2026. That pattern, a release candidate cycle followed by a final build, is visible in the release list and suggests changes are staged rather than pushed straight to users. The README points at the releases page for changes rather than keeping a changelog in the repository, so upgrade notes live there.

TrenchBroom is GPL-3.0. For a mapper, that means the editor is free to use and the source is available. For anyone embedding the code in another product, the licence carries obligations that a permissive licence does not, and the repository ships LICENSE.txt at the root as the authoritative text. This is not legal advice; if you plan to redistribute or link the code, read LICENSE.txt and get your own counsel.

The upgrade cost is mostly about your game configuration and your map files. The README does not document a migration path between editor versions, and it does not promise that configurations written for one release keep working in the next. If you maintain a custom configuration for the Generic target, keep it under version control and re-check it after each release rather than assuming it carries over.

Editorial conclusion

Adopt TrenchBroom if you map for Quake, Quake 2, Hexen 2, Daikatana or a custom Quake-engine game, and you want brush editing, CSG and a UV view without paying for a licence. Do not adopt it if you need Quake 3 patches or brush primitives, or if your project is a Godot or Unity scene, because the editor writes Quake map files rather than engine-native scenes. Before committing, open the manual at trenchbroom.github.io/manual/latest, read BUILD.md if you plan to compile rather than download, and confirm that your target game has a configuration in the editor. The README lists the supported games explicitly, and Quake 3 is marked partial.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. TrenchBroom/TrenchBroom on GitHub