118 lines
6.6 KiB
Markdown
118 lines
6.6 KiB
Markdown
|
# TrenchBroom round-trip
|
||
|
|
|
||
|
|
Generate a dungeon procedurally → edit it by hand in TrenchBroom → load the
|
||
|
|
edited map back into Godot with typed entities wired up via FuncGodot.
|
||
|
|
|
||
|
|
```
|
||
|
|
BrogueGen / Blobber
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
export_map.gd ──► demo/maps/generated.map ◄──► TrenchBroom
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
demo/scenes/dungeon_from_map.tscn
|
||
|
|
│
|
||
|
|
▼
|
||
|
|
FuncGodotMap
|
||
|
|
(instantiates entity scenes)
|
||
|
|
```
|
||
|
|
|
||
|
|
## Prerequisites
|
||
|
|
|
||
|
|
- **Godot 4.6+** on PATH as `godot`.
|
||
|
|
- **FuncGodot addon** installed under [demo/addons/func_godot/](../addons/func_godot/) and enabled in Project Settings → Plugins (already wired up in [demo/project.godot](../project.godot)).
|
||
|
|
- **Brogue-Genesis GDExtension** built: `make godot` from the repo root. This produces [demo/addons/brogue_gen/bin/libbrogue_gen.linux.template_debug.x86_64.so](../addons/brogue_gen/bin/) and exposes the `BrogueGen` class to GDScript.
|
||
|
|
- **TrenchBroom** installed (`flatpak install com.kristianduske.TrenchBroom` or distro package).
|
||
|
|
|
||
|
|
## One-time setup
|
||
|
|
|
||
|
|
Install the TrenchBroom game config + FGD:
|
||
|
|
|
||
|
|
```
|
||
|
|
make tb-sync
|
||
|
|
```
|
||
|
|
|
||
|
|
This writes `GameConfig.cfg` and `FuncGodot.fgd` into `~/.TrenchBroom/games/brogue-genesis/`. In TrenchBroom, open Preferences → Games → `brogue-genesis` → set the "Game Path" to this repo's `demo/` directory (anywhere works, but `demo/` lets TB find `maps/` relative paths).
|
||
|
|
|
||
|
|
Re-run `make tb-sync` any time you:
|
||
|
|
|
||
|
|
- Add or remove an entity under [data/entities/](../data/entities/).
|
||
|
|
- Edit [data/fgd/brogue_fgd.tres](../data/fgd/brogue_fgd.tres).
|
||
|
|
- Change the GameConfig template in [scripts/export_tb_config.gd](../scripts/export_tb_config.gd).
|
||
|
|
|
||
|
|
## Day-to-day workflow
|
||
|
|
|
||
|
|
### 1. Generate a map
|
||
|
|
|
||
|
|
```
|
||
|
|
make map # defaults: brogue, seed=42, depth=20, 1 level
|
||
|
|
make map SEED=77 DEPTH=30 LEVELS=4 # override
|
||
|
|
make map GENERATOR=blobber LEVELS=3 # use the 3D blobber path
|
||
|
|
```
|
||
|
|
|
||
|
|
Output lands at `demo/maps/generated.map` (`MAP_OUT=` overrides the path).
|
||
|
|
|
||
|
|
### 2. Edit in TrenchBroom
|
||
|
|
|
||
|
|
Launch TrenchBroom → New Map → pick the `brogue-genesis` game → File → Open `demo/maps/generated.map`. Move brushes, place entities, save back to the same path.
|
||
|
|
|
||
|
|
Entities visible in TB's entity browser:
|
||
|
|
|
||
|
|
| Classname | Type | Purpose |
|
||
|
|
|----------------------|----------|------------------------------------------------------------|
|
||
|
|
| `point_player_start` | point | Party spawn. Emitted once per map at level-0 stairs-up. |
|
||
|
|
| `point_stair_up` | point | Interact marker to climb a level. |
|
||
|
|
| `point_stair_down` | point | Interact marker to descend a level. |
|
||
|
|
| `point_door` | point | Door marker (angle property controls orientation). |
|
||
|
|
| `func_water` | solid | Water volume — slow movement, extinguish fire. |
|
||
|
|
| `func_lava` | solid | Lava volume — damage on entry + burn debuff. |
|
||
|
|
| `worldspawn` | solid | Default static geometry (floors, walls, ceilings). |
|
||
|
|
|
||
|
|
### 3. Rebuild in Godot
|
||
|
|
|
||
|
|
Open [demo/scenes/dungeon_from_map.tscn](../scenes/dungeon_from_map.tscn) → select the `FuncGodotMap` node → click **Build Map** in the Inspector. Brushes become `MeshInstance3D`s, entity brushes become `Area3D`s, point entities instantiate their scene files from `data/entities/{name}/`.
|
||
|
|
|
||
|
|
Save the scene to persist the built nodes.
|
||
|
|
|
||
|
|
## Makefile targets
|
||
|
|
|
||
|
|
| Target | What it does | Variables |
|
||
|
|
|------------|--------------------------------------------------------------------|--------------------------------------------|
|
||
|
|
| `make map` | Run `export_map.gd` → writes `.map` file | `GENERATOR, SEED, DEPTH, LEVELS, MAP_OUT` |
|
||
|
|
| `make tb-sync` | Run `export_tb_config.gd` → writes GameConfig.cfg + FuncGodot.fgd | `TB_GAME_DIR` (default: `~/.TrenchBroom/games/brogue-genesis`) |
|
||
|
|
| `make godot` | Build the GDExtension | — |
|
||
|
|
|
||
|
|
## Raw CLI (if Make isn't available)
|
||
|
|
|
||
|
|
```
|
||
|
|
# Generate a .map
|
||
|
|
godot --headless --path demo --script scripts/export_map.gd -- \
|
||
|
|
--generator brogue --seed 42 --depth 20 --levels 2 \
|
||
|
|
--out /abs/path/demo/maps/generated.map
|
||
|
|
|
||
|
|
# Sync TrenchBroom config
|
||
|
|
godot --headless --path demo --script scripts/export_tb_config.gd -- \
|
||
|
|
/home/$USER/.TrenchBroom/games/brogue-genesis
|
||
|
|
```
|
||
|
|
|
||
|
|
Legacy positional form for `export_map.gd` (still supported, brogue only): `SEED DEPTH [LEVELS] OUT.map`.
|
||
|
|
|
||
|
|
## Adding a new entity type
|
||
|
|
|
||
|
|
1. Create `demo/data/entities/<classname>/<classname>.tres` (a `FuncGodotFGDPointClass` or `FuncGodotFGDSolidClass`) and a `<classname>.tscn` scene for it to instantiate.
|
||
|
|
2. Add the `.tres` to the `entity_definitions` array in [data/fgd/brogue_fgd.tres](../data/fgd/brogue_fgd.tres).
|
||
|
|
3. If the exporter needs to emit it, teach [scripts/export_map.gd](../scripts/export_map.gd) to recognize whatever terrain/liquid tag drives it — see the `_emit_point_entities` / `_emit_liquid_entities` helpers.
|
||
|
|
4. `make tb-sync` so TrenchBroom picks up the new class.
|
||
|
|
|
||
|
|
## Troubleshooting
|
||
|
|
|
||
|
|
**TrenchBroom says "Unknown game: brogue-genesis"** — Preferences → Games → make sure `brogue-genesis` appears. If not, `~/.TrenchBroom/games/brogue-genesis/GameConfig.cfg` is missing. Run `make tb-sync`.
|
||
|
|
|
||
|
|
**FuncGodot "Build Map" does nothing / errors about missing class** — `brogue_fgd.tres` references a `.tres` that doesn't exist, or the addon isn't enabled. Check Project Settings → Plugins.
|
||
|
|
|
||
|
|
**`BrogueGen.new()` crashes with "class not found" in headless** — The GDExtension wasn't built, or only the `template_debug` variant is present and Godot is launched against `template_release`. Run `make godot`. For editor-time tool scripts, the extension needs a `linux.editor.x86_64` entry in [addons/brogue_gen/brogue_gen.gdextension](../addons/brogue_gen/brogue_gen.gdextension) (already wired).
|
||
|
|
|
||
|
|
**Player spawn ends up inside a wall** — Exporter picks level-0's first `T_STAIRS_UP` cell, else first walkable. If neither yields a good spawn, move the `point_player_start` entity by hand in TrenchBroom; next rebuild in Godot preserves it.
|
||
|
|
|
||
|
|
**Lots of `point_door` entities from the blobber generator** — Blobber treats every `FT_DOOR_SILL` cell as a door, so multi-cell doorways emit multiple entities. A future pass can merge adjacent door cells into one entity with an `extent` property.
|