trench/docs/FUNC_GODOT_TRENCHBROOM_SETUP.md

Setting Up a New Godot Project with FuncGodot + TrenchBroom

Step-by-step guide for using TrenchBroom as a level editor with Godot via the FuncGodot addon. Tested on Linux with Godot 4.6, FuncGodot 2025.12, and TrenchBroom (v9 game config format).

---

Overview

There are three things you configure, and they must agree with each other:

What	Where it lives	What it controls
FuncGodotLocalConfig	addons/func_godot/func_godot_local_config.tres	Machine-specific paths (where to export configs, where your project lives on disk)
Your FGD resource	A .tres you create in your project	Entity definitions + the FGD filename used in TrenchBroom
Your TrenchBroom GameConfig resource	A .tres you create in your project	Game name, texture root, FGD reference — exports to TrenchBroom's games directory

FuncGodotMapSettings also matters but has sane defaults. The critical thing is that paths line up.

---

Step 1: Install FuncGodot

1. Copy the addons/func_godot/ folder into your project's addons/ directory (or install via AssetLib).
2. In Godot: Project > Project Settings > Plugins — enable FuncGodot.
3. Restart the editor if prompted.

---

Step 2: Create Your Texture Directory

Put your textures in a subdirectory inside res://textures/. Do NOT put them directly in res://textures/.

your_project/
  textures/
    my_textures/        <-- subdirectory required
      brick.png
      stone.png
      metal.png

Linux users: Make sure file extensions are lowercase (.png not .PNG). Both TrenchBroom and Godot are case-sensitive on Linux.

---

Step 3: Create Your FGD Resource

Do NOT edit the default addons/func_godot/fgd/func_godot_fgd.tres. Create your own.

1. In the Godot FileSystem panel, right-click your project root.
2. New Resource > search for FuncGodotFGDFile > Create.
3. Save it as something like my_game_fgd.tres in your project root.
4. In the inspector, set:
   • FGD Name: my_game (this becomes the .fgd filename — no spaces, no extension)
   • Base FGD Files: Add res://addons/func_godot/fgd/func_godot_fgd.tres (this pulls in all the default entities like worldspawn, func_geo, etc.)
   • Entity Definitions: Leave empty for now. Add your custom entities here later.

Why this matters: The FGD Name you set here becomes both the exported .fgd filename AND the filename referenced inside GameConfig.cfg. If these don't match, TrenchBroom silently falls back to a different FGD or fails to load entities.

---

Step 4: Create Your TrenchBroom GameConfig Resource

1. In Godot FileSystem, right-click your project root.
2. New Resource > search for TrenchBroomGameConfig > Create.
3. Save it as something like my_game_tb_config.tres in your project root.
4. In the inspector, set:
   • Game Name: Something unique to this project (e.g. my_game). This is the name shown in TrenchBroom's game list. Do not reuse "FuncGodot" — it will collide with other projects.
   • Textures > Textures Root Folder: textures (this is relative to the game path, NOT a res:// path)
   • Entities > FGD File: Point to your FGD resource from Step 3 (res://my_game_fgd.tres)
   • Leave everything else at defaults unless you have a reason to change it.

---

Step 5: Configure FuncGodotLocalConfig

This stores machine-specific paths in a JSON file outside your project, so it won't break when you move the project or work on a different machine.

1. Open addons/func_godot/func_godot_local_config.tres in the inspector.
2. Set these fields:

Field	Value	Example
Trenchbroom Game Config Folder	The folder inside TrenchBroom's games directory for THIS game. Must be a full filesystem path.	/home/you/.TrenchBroom/games/my_game
Map Editor Game Path	Your Godot project root as a full filesystem path. TrenchBroom uses this to find textures.	/home/you/godot_projects/my_game
FGD Output Folder	Usually same as your project root. Only used for standalone FGD export.	/home/you/godot_projects/my_game

3. Click Export func_godot settings (the save button) to write these to disk.

Where this actually saves: ~/.local/share/godot/app_userdata/<YourProjectName>/func_godot_config.json on Linux. If you clone the project to a new machine, you'll need to redo this step.

---

Step 6: Export the GameConfig to TrenchBroom

1. Click on your TrenchBroom GameConfig resource (my_game_tb_config.tres) in the inspector.
2. Click Export GameConfig (the button at the top of the inspector).
3. Check the Godot output panel — it should print paths for the icon, GameConfig.cfg, and FGD file.

This creates three files in your TrenchBroom games folder:

~/.TrenchBroom/games/my_game/
  GameConfig.cfg    <-- tells TrenchBroom about your game
  my_game.fgd       <-- entity definitions (name matches your fgd_name)
  icon.png           <-- 32x32 icon

---

Step 7: Configure TrenchBroom

1. Open TrenchBroom.
2. Your game should appear in the game list on the welcome screen. Select it.
3. If it doesn't appear or textures don't load, go to View > Preferences > Games:
   • Select your game name.
   • Set Game Path to your Godot project root (same path as Map Editor Game Path from Step 5).
4. Create a new map. Choose Valve format (recommended — it has per-face UV axes).

Your textures should now appear in TrenchBroom's texture browser under my_textures/brick, my_textures/stone, etc.

---

Step 8: Build a Map and Import into Godot

1. Build your map in TrenchBroom. Save the .map file inside your Godot project directory (e.g. res://maps/my_level.map).
2. Back in Godot, the .map file will auto-import as a resource.
3. Create a new 3D scene. Add a FuncGodotMap node.
4. In the inspector:
   • Local Map File: Set to your .map file (res://maps/my_level.map)
   • Map Settings: You can use the default (addons/func_godot/func_godot_default_map_settings.tres) or create your own FuncGodotMapSettings resource. Make sure base_texture_dir is res://textures and entity_fgd points to your FGD resource.
5. Click Build Map in the toolbar (or the button on the FuncGodotMap node).

---

How the Paths Must Align

This is where things break if you're not careful. The texture name in the .map file must resolve to the same file in both TrenchBroom and Godot.

TrenchBroom resolves textures as:
  <Game Path> / <textures_root_folder> / <subdirectory> / <texture>.png
  /home/you/my_project / textures / my_textures / brick.png

Godot resolves textures as:
  <base_texture_dir> / <texture_name_from_map> . <extension>
  res://textures / my_textures/brick . png

The .map file stores: my_textures/brick

If Game Path + textures_root_folder doesn't point to the same physical directory as base_texture_dir, textures will show in TrenchBroom but not in Godot (or vice versa).

---

Quick Checklist for New Projects

• FuncGodot addon installed and enabled
• Textures in a subdirectory of res://textures/ with lowercase extensions
• Created your own FGD resource (not editing the addon default)
  • fgd_name set to something unique
  • Default FGD added to base_fgd_files
• Created your own TrenchBroom GameConfig resource
  • game_name set to something unique (not "FuncGodot")
  • textures_root_folder set to textures
  • fgd_file pointing to your FGD resource
• FuncGodotLocalConfig paths set and exported:
  • trenchbroom_game_config_folder = ~/.TrenchBroom/games/<your_game>
  • map_editor_game_path = your project root (full filesystem path)
• Clicked "Export GameConfig" on your TrenchBroom GameConfig resource
• In TrenchBroom: game path set to your Godot project root
• No leftover ~/.TrenchBroom/games/ directories from old projects with the same game name

---

Troubleshooting

Textures don't appear in TrenchBroom:

• Check that the Game Path in TrenchBroom preferences points to your Godot project root.
• Verify textures_root_folder in your GameConfig resource matches your actual directory name.
• On Linux: file extensions must be lowercase (.png not .PNG).
• Re-export GameConfig after any changes.

TrenchBroom loads wrong FGD / entities missing:

• Check ~/.TrenchBroom/games/ for duplicate directories with the same "name" in their GameConfig.cfg. Delete stale ones.
• The FGD filename in GameConfig.cfg ("definitions" field) must match the actual .fgd file on disk. Both come from your FGD resource's fgd_name property — re-export to resync.

Textures show in TrenchBroom but not in Godot after map build:

• base_texture_dir in your FuncGodotMapSettings must be res://textures (matching the physical directory that TrenchBroom's game path + textures root points to).
• Texture names are case-sensitive on Linux. The name in the .map file must match the filename exactly.
• Check the Godot output panel for "Error: Texture load failed" messages.

FuncGodotLocalConfig settings don't stick:

• You must click "Export func_godot settings" after changing values. The .tres file itself doesn't store the data — it goes to a JSON file in Godot's user data directory.
• After cloning to a new machine, re-enter and re-export all local config settings.

Map file not recognized by Godot:

• The .map file must be inside your Godot project directory (under res://).
• FuncGodot must be enabled in Project Settings > Plugins.