initial commit
This commit is contained in:
saarsena@gmail.com
commit
c2bb3893a9
1038 changed files with 75846 additions and 0 deletions
199
docs/FUNC_GODOT_TRENCHBROOM_SETUP.md
Normal file
199
docs/FUNC_GODOT_TRENCHBROOM_SETUP.md
Normal file
|
|
@ -0,0 +1,199 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue