---
title: Mapping with TrenchBroom and Func Godot
summary: A Beginners Guide
image: https://pfy.ch/guide-images/trenchbroom/trenchbroom-entities.png
publishedAt: 1717288549897
updatedAt: 1717543060000
---

<style>
img {
    max-width: unset !important;
    max-height: 500px;
}
</style>

While setting up `func_godot` I found the documentation very overwhelming as a beginner - everything you need is there, but it's not laid out in a step by step easy to follow process.

The following is a personal guide that I made if I ever have to set up a project again.

# Table of Contents

- [Required files](#required-files)
- [Getting Started](#getting-started)
  - [Setting up Godot](#setting-up-godot)
  - [Configuring TrenchBroom](#configuring-trenchbroom)
  - [Compiling the map in Godot](#compiling-the-map-in-godot)
  - [Adding Textures](#adding-textures)
  - [Custom Entities](#custom-entities)
    - [Placing Scenes via TrenchBroom](#placing-scenes-via-trenchbroom)
    - [Placing Nodes via TrenchBroom](#placing-nodes-via-trenchbroom)

# Required files

The following resources are required:

- [Release of Func Godot](https://github.com/func-godot/func_godot_plugin) _(2024.1.1 used)_
- [TrenchBroom](https://github.com/func-godot/func_godot_plugin) _(2024.1 used)_
- [Godot 4](https://godotengine.org/)  _(v4.2.2.stable.arch_linux used)_

```bash
yay -Syyu godot trenchbroom-bin
```

# Getting Started

## Setting up Godot

Before setting up TrenchBroom you must first set up the plugin - since it will generate files required for TrenchBroom.

1. Create a new Godot project and copy the `addons` folder from your Func Godot release into the project root 
2. Navigate to "Project" > "Project Settings" > "Plugins" and enable the plugin
3. Create the folders `trenchbroom` & `trenchbroom/textures` in your project root
4. Open `res://addons/func_godot/func_godot_local_config.tres` and set the following fields:
   - **Fgd Output Folder**: This is where the custom TrenchBroom game definition will live. Set the value to something like this:  
     - `/home/user/.TrenchBroom/games/demo` where "user" is your username and "demo" is the name of your project.
   - **TrenchBroom Game Config Folder**: This should be exactly the same as "Fgd Output Folder"
   - **Map Editor Game Path**: Set this path to the "TrenchBroom" folder in your Godot Project:  
     - `/home/user/Developer/demo-godot/trenchbroom` 
5. Click "Export Func Godot Settings" - It looks like a toggle, but it's actually a button.

![](/guide-images/trenchbroom/func_godot_local_config.png)

6. Right-click the `trenchbroom` folder in your project root and "Create New" > "Resource"
7. Create a new `FuncGodotFGDFile` and save it in the trenchbroom folder as "primary_fgd.tres"
8. Set the "Base FGD File" value to `res://addons/func_godot/fgd/func_godot_fgd.tres`

![](/guide-images/trenchbroom/func_godot_fgd_file.png)

9. Open `res://addons/func_godot/func_godot_default_map_settings.tres` and set the following:
   - **Entity Fgd**: Set this to the FGD we created earlier  
     - i.e. `res://trenchbroom/primary_fgd.tres`
   - **Base Texture Dir**: Set this to your map texture directory.  
     - i.e. `res://trenchbroom/textures` to keep map textures separate to game textures

![](/guide-images/trenchbroom/func_godot_default_map_settings.png)

10. Next open `res://addons/func_godot/game_config/trenchbroom/func_godot_tb_game_config.tres` and set the following:
    - **Game Name**: The folder name you wrote in "Fgd Output Folder"  
      - i.e. `Demo` 
11. Click "Export File"

![](/guide-images/trenchbroom/func_godot_tb_game_config.png)

## Configuring TrenchBroom

1. Open TrenchBroom and click "New map..."
2. Click "Open preferences..."
3. Your games name should be listed in the games list - select it
4. Set the game path to the `res://trenchbroom/` folder in your Godot project root
   - i.e. `/home/user/Developer/demo/trenchbroom`
5. Click "Apply" the "Ok"
6. Select your game from the right hand list then click "Ok"
7. Save the newly created map to your Godot project
   - i.e. `/home/user/Developer/demo/maps/`

## Compiling the map in Godot

1. Back in Godot create a new 3D scene and save it
    - i.e. `res://scenes/main.tscn`
2. Add a `FuncGodotMap` node to this scene
3. Set the "Local Map File" to the map you just saved
    - i.e. `res://maps/main.map`
4. Click Build in the toolbar - You should see the default TrenchBroom cube as a mesh in Godot

![](/guide-images/trenchbroom/FuncGodotMap.png)

## Adding Textures

I use a site like [AmbientCG](https://ambientcg.com) for quick textures - I'll be using [this brick texture](https://ambientcg.com/view?id=Bricks085) in 4K as an example 

1. Copy your texture jpg into `res://trenchbroom/textures`
   - If your texture comes with normals, ao, roughness, displacements etc do the following:
     1. Create a folder with the same name as the root texture
        - `res://trenchbroom/textures/bricks`
     2. Copy the files into this folder with the following naming convention:
        - `bricks_ao.jpg` - Ambient occlusion
        - `bricks_roughness.jpg` - Roughness
        - `bricks_displacement.jpg` - Displacement
        - `bricks_normal.jpg` - Normal maps
2. In Godot select all your imported textures in the file browser
3. Click "Import" at the top & ensure "mode" is "VRAM uncompressed"
4. Click "Re-import"

![](/guide-images/trenchbroom/textures.png)

5. Inside TrenchBroom press F5 or "File" > "Reload Texture Collections"
6. You should now be able to apply the texture to brushes in TrenchBroom
   - With 4k textures - I usually set the scale to `0.05`

![](/guide-images/trenchbroom/trenchbroom-textures.png)

7. Back in Godot - Select your `FuncGodotMap` node and click "Build" & "Unwrap UV2". You should now see your texture applied.
   - You can confirm all your materials applied correctly by checking the generated `.tres` file in your textures folder
     - i.e .`res://trenchbroom/textures/bricks.tres`

![](/guide-images/trenchbroom/godot-textures.png)

## Custom Entities

Jumping over into a different project (configured the same way), you may want to place entities such as lights, enemies, the player, etc. in your map via TrenchBroom. This can be quite complex however I have figured out the following

### Placing Scenes via TrenchBroom

1. Create the folder `res://TrenchBroom/entities`
2. Right-click and "Create New" > "Resource"
3. Create a `FuncGodotFGDPointClass` and name it after your entity
4. Set the following values:
   - **Scene**
      - **Scene File**: The scene you want to create
        - i.e. `character.tscn`
   - **Entity Definition**
     - **Class Name**: The name of the entity in TrenchBroom
     - **Description**: The description of the entity in TrenchBroom
     - **Meta Properties**: The size and colour of the entity in TrenchBroom

![](/guide-images/trenchbroom/player-entity.png)

5. Open `res://TrenchBroom/primary_fgd.tres`
6. Under "Entity Definitions" add your new `.tres` file
7. Click "Export File"
8. In TrenchBroom, ensure the entities mod is enabled in the "Map" tab and press F6 or "File" > "Reload Entity Definitions" to reload entities

![](/guide-images/trenchbroom/trenchbroom-entities.png)

9. Back in Godot re-build your map and your entity should be present

![](/guide-images/trenchbroom/entities-godot.png)

### Placing nodes via TrenchBroom

Placing nodes like lights via TrenchBroom is a bit more complicated (I havent figured it out). But it's 100% possible & I've seen it done in the Discord. Once I have done it myself I will document the process here.

There are examples in this [GitHub Repo](https://github.com/func-godot/func_godot_example_basic/tree/main) which seem to work.