# 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.