7. TrenchBroom - QodotPlugin/qodot-plugin GitHub Wiki

This Wiki is outdated and no longer being maintained. Qodot's new documentation can be found here: https://qodotplugin.github.io

TrenchBroom is a cross platform level editor for Quake-engine based games. It supports Quake, Quake 2, and Hexen 2 and runs on Windows (XP and newer), Mac OS X (10.6 and newer) and Linux. TrenchBroom is easy to use and provides many simple and advanced tools to create complex and interesting levels with ease.

Before setting up Trenchbroom, make sure you've created a Game Definition Folder for Trenchbroom using the Qodot_Trenchbroom_Config_Folder.tres file in your Godot project (with Qodot installed). If you haven't, read the Usage page on how to export a Game Definition for your Godot project. Make sure this new folder is placed in the Trenchbroom/games/ folder of your Trenchbroom installation.

Launch Trenchbroom, click "New Map..." and select your game's name and icon from the Select Game list.

Once it's selected, click "Open preferences..." and find your game from the preferences list.

Under "Game Path", click the ellipsis "..." and select your game project folder, then click Apply.

This step is to connect your project's textures with Trenchbroom. Inside of Trenchbroom, click the word "Face" in the top-right, followed by "Texture Collections" at the bottom-right of the window. A list should pop-up with names like textures\<group>, where <group> is a subfolder of your texture directory.

Select the collections you'd like to use (or select all of them if you're unsure) and click the "+" button at the bottom of the panel. If there are no names in the Texture Collections list, press F6 or double-check that your Game Path is set correctly.

Trenchbroom should now read textures directly from your Godot project.

Optionally, create a folder in your Godot project to store your .map files, and create a folder inside that called "autosave". To prevent Godot from re-importing Trenchbroom's automatic map-backups, add an empty file to the autosave folder with the filename .gdignore.

This is the top-level class governing TrenchBroom game configuration export, and represents the game configuration folder itself.

Export File - Used as button to export the selected TrenchBroom game definition to the specified folder. Game Config File and FGD File resources will automatically be exported with the appropriate internal references as part of thie process.

TrenchBroom Games Folder - The destination folder used for game configuration export.

Game Name - The name of your game, as displayed in the TrenchBroom UI. Overrides the identically-named property inside TrenchBroomGameDefinitionFile during export.

Icon - Your game's icon, as displayed in the TrenchBroom UI. This will automatically be resized to the correct dimensions during export.

Game Config File - A TrenchBroomGameDefinitionFile resource used to represent GameConfig.cfg

FGD Files - An array of QodotFGDFile resources exported into the game config folder.

This resource represents the GameConfig.cfg file in a TrenchBroom game configuration folder.

Export File - Used as a button to export the selected game config to the target file.

Target File - Destination file used during export.

Game Name - The name of your game, as displayed in the TrenchBroom UI.

Brush Tags - An array of TrenchBroomTag resources used to specify per-brush metadata.

Face Tags - An array of TrenchBroomTag resources used to specify per-face metadata.

Face Attrib Surface Flags - An array of TrenchBroomFaceAttrib resources used to specify format-specific surface attributes. Specific to Quake 2, Quake 3 and Daikatana formats, included for compatibility.

Face Attrib Content Flags - An array of TrenchBroomFaceAttrib resources used to specify format-specific content attributes. Specific to Quake 2, Quake 3 and Daikatana formats, included for compatibility.

FGD Filenames - An array of string filenames defining the FGD files associated with this game config.

This resource represents a brush or face tag inside a TrenchBroomGameDefinitionFile, used for defining map editor-specific metadata such as which brush classnames or face textures should be rendered as transparent.

Tag Name - The tag's name.

Tag Attributes - A set of string keys defining editor-specific properties.

Tag Match Type - Determines how this tag will be automatically applied.

Tag Pattern - Expression to match against when automatically applying tags.

Texture Name - Texture name to automatically apply to when using the Texture tag match type.

This resource represents a per-face set of bitmask flags used by certain variants of the map format.

Attrib Name - Internal name for this attribute.

Attrib Description - Description of this attribute, as displayed in a compatible editor.

TrenchBroom implements an entity grouping system based on metadata saved to the map file. These groups can be nested to arbitrary depth, so Qodot can use them to reconstruct a tree hierarchy during build:

This is controlled by the Trenchbroom Nested Groups property on QodotMap.

Each group needs an entity to use as its root when imported into Godot, so they should be created with a 1:1 relationship to avoid unexpected behavior. Groups can be freely nested inside other groups, so long as each one contains a single entity.

Worldspawn brushes are not subject to this limitation, and thus can be used freely inside nested groups.

Each group's transform will be centered on its root entity, so this feature can be used to create complex tree hierarchies with controllable transform origins.

An example TrenchBroom game configuration is available with the plugin, and can be found in addons/qodot/game-definitions/trenchbroom. In addition, an extended game configuration with extra custom entity types ships with the qodot-example repo.

TrenchBroom will create an 'autosaves' folder containing map backups alongside any maps you edit with it, so make sure to create a .gdignore file within to prevent Godot from repeatedly importing several versions of the same map.