Skip to main content

​
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 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

EntryRole
dungeon_categoryGroups dungeons for the browser menu
dungeon_instanceOne dungeon: template world, rules, costs, party size
dungeon_room_configThe room set + spawn point used by an instance
dungeon_roomA polygon area with onEnter/onLeave triggers, priority and criteria
dungeon_loot_chestRandomized reward container (NPC anchor or manual trigger)
dungeon_enter / dungeon_leave / dungeon_closeRun 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.
  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 — the browser: categories and dungeons, difficulty icons, locked/unlocked states.
  • 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). Everything else — borders, scrollable lists, composite stacking, sounds, cooldowns — is standard GUI behavior. A minimal browser skeleton: 
"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": {} }
  ] } }
]
Prototype the layout as a plain open_gui menu first using the GUI cookbook, then move the pool into the dungeon menu entry and tag the dynamic slots.

​
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 exposes run state (completions, current room…) to the Typewriter fact system — usable in criteria anywhere: menu visibility, room triggers, quest conditions.

​
Troubleshooting

SymptomLikely cause
Menu doesn’t openGUI Extension missing or its layout pool has no valid mainLayoutId
Buttons show but do nothingDynamic slots not tagged with the expected buttonType
Room triggers never firePolygon not closed / wrong world — re-check in the room editor
Players spawn at world origindungeon_room_config spawn point unset for that instance