> ## Documentation Index
> Fetch the complete documentation index at: https://docs.borntocraftstudio.net/llms.txt
> Use this file to discover all available pages before exploring further.

# Getting Started

> From zero to a running dungeon — entries, rooms, and the GUI-powered menus explained step by step

# Getting Started

The Dungeon Extension turns Typewriter entries into **instanced dungeon runs**: each group gets its own world copy, rooms react to players entering polygons, and loot chests hand out rewards. Its two menus (dungeon browser and party lobby) are **regular GUI Extension layouts** that you design yourself.

New to the menu system? Read the [GUI Introduction](/extensions/Typewriter-GUIExtension/guide/introduction) first — the dungeon menus reuse `layoutPool` / `mainLayoutId` exactly as described there. **The GUI Extension is a hard dependency: without it, no dungeon menu will open.**

## How the pieces fit

```mermaid theme={null}
graph LR
    A["dungeon_category<br/>(groups dungeons)"] --> B["dungeon_global_menu<br/>(browser — GUI layout)"]
    B --> C["dungeon_party_menu<br/>(lobby — GUI layout)"]
    C --> D["dungeon_enter<br/>(instance created)"]
    D --> E["rooms + loot chests<br/>(gameplay)"]
    E --> F["dungeon_leave / dungeon_close"]
```

| Entry                                                                                                                                                                                                                                                                       | Role                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| [`dungeon_category`](/extensions/TypeWriter-DungeonExtension/entries/definition/dungeon_category)                                                                                                                                                                           | Groups dungeons for the browser menu                                |
| [`dungeon_instance`](/extensions/TypeWriter-DungeonExtension/entries/definition/dungeon_instance)                                                                                                                                                                           | One dungeon: template world, rules, costs, party size               |
| [`dungeon_room_config`](/extensions/TypeWriter-DungeonExtension/entries/definition/dungeon_room_config)                                                                                                                                                                     | The room set + spawn point used by an instance                      |
| [`dungeon_room`](/extensions/TypeWriter-DungeonExtension/entries/definition/dungeon_room)                                                                                                                                                                                   | A polygon area with onEnter/onLeave triggers, priority and criteria |
| [`dungeon_loot_chest`](/extensions/TypeWriter-DungeonExtension/entries/definition/dungeon_loot_chest)                                                                                                                                                                       | Randomized reward container (NPC anchor or manual trigger)          |
| [`dungeon_enter`](/extensions/TypeWriter-DungeonExtension/entries/action/dungeon_enter) / [`dungeon_leave`](/extensions/TypeWriter-DungeonExtension/entries/action/dungeon_leave) / [`dungeon_close`](/extensions/TypeWriter-DungeonExtension/entries/action/dungeon_close) | Run lifecycle actions                                               |

## Step 1 — Define a dungeon

1. Create a **`dungeon_instance`**: pick the template world, party size limits, entry costs and rules.
2. Create a **`dungeon_room_config`** pointing at your room set and spawn point, and link it from the instance.
3. Draw your **`dungeon_room`** polygons with the in-game **room editor** (particle edges, node handles, toolbar) and attach `onEnter`/`onLeave` triggers — this is where fights, cinematics and door logic hook in.
4. Optionally place **`dungeon_loot_chest`** entries, either anchored to NPCs or fired manually via [`loot_chest_trigger`](/extensions/TypeWriter-DungeonExtension/entries/action/loot_chest_trigger).
5. Group instances under a **`dungeon_category`**.

## Step 2 — Design the menus (GUI layouts)

Both menu actions carry a full GUI `layoutPool`, so their look is entirely yours:

* [`dungeon_global_menu`](/extensions/TypeWriter-DungeonExtension/entries/action/dungeon_global_menu) — the **browser**: categories and dungeons, difficulty icons, locked/unlocked states.
* [`dungeon_party_menu`](/extensions/TypeWriter-DungeonExtension/entries/action/dungeon_party_menu) — the **lobby**: member list, ready/not-ready toggles, start button.

Dungeon-specific buttons are ordinary GUI items tagged with a `buttonType` (the dungeon resolver fills them — the GUI docs call this the [`buttonType` / `buttonPrefix` mechanism](/extensions/Typewriter-GUIExtension/guide/interactions)). Everything else — borders, [scrollable lists](/extensions/Typewriter-GUIExtension/guide/layouts#scrollable), [composite stacking](/extensions/Typewriter-GUIExtension/guide/layouts#composite), sounds, [cooldowns](/extensions/Typewriter-GUIExtension/guide/interactions) — is standard GUI behavior.

A minimal browser skeleton:

```json theme={null}
"mainLayoutId": "main",
"layoutPool": [
  { "case": "composite", "value": { "id": "main", "children": ["border", "dungeon_list"] } },
  { "case": "simple", "value": { "id": "border", "items": [
      { "x": 0, "y": 0, "count": 9, "direction": "right",
        "item": { "material": "GRAY_STAINED_GLASS_PANE" }, "displayName": " " }
  ] } },
  { "case": "simple", "value": { "id": "dungeon_list", "items": [
      { "x": 1, "y": 2, "buttonType": "<dungeon button type>", "item": {} }
  ] } }
]
```

<Tip>
  Prototype the layout as a plain `open_gui` menu first using the [GUI cookbook](/extensions/Typewriter-GUIExtension/guide/cookbook), then move the pool into the dungeon menu entry and tag the dynamic slots.
</Tip>

## Step 3 — Wire the flow

1. Open the browser from an NPC or command: trigger **`dungeon_global_menu`**.
2. Selecting a dungeon opens **`dungeon_party_menu`** (built-in lobby works standalone; Parties/MMOCore adapters are optional).
3. When everyone is ready, the lobby fires **`dungeon_enter`**: the instance world is created and the party is teleported to the room config's spawn.
4. **`dungeon_leave`** handles individual exits; **`dungeon_close`** shuts the instance down and cleans up the world.

## Facts & progress

[`dungeon_facts`](/extensions/TypeWriter-DungeonExtension/entries/definition/dungeon_facts) exposes run state (completions, current room…) to the Typewriter fact system — usable in criteria anywhere: menu visibility, room triggers, quest conditions.

## Troubleshooting

| Symptom                       | Likely cause                                                         |
| ----------------------------- | -------------------------------------------------------------------- |
| Menu doesn't open             | GUI Extension missing or its layout pool has no valid `mainLayoutId` |
| Buttons show but do nothing   | Dynamic slots not tagged with the expected `buttonType`              |
| Room triggers never fire      | Polygon not closed / wrong world — re-check in the room editor       |
| Players spawn at world origin | `dungeon_room_config` spawn point unset for that instance            |