bgen/demo/docs/trenchbroom.md

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