Dungeon

Official compatibility

Element	Reference
TypeWriter	Required. Use the official TypeWriter release supported by the extension release.
Related extensions	Install the related extensions listed on this page before using entries that depend on them.

The Dungeon Extension provides a comprehensive framework for creating and managing instanced dungeons with polygon-based room detection, global/party menus, loot chests, and party synchronization.

Features

• Instanced Worlds — Dedicated worlds created per dungeon run with template-based generation.
  • Rooms & Triggers — Polygon-based rooms with onEnter/onLeave triggers, priority, and criteria.
  • Menu System — Global dungeon browser + party lobby with full GUI layout customization.
  • Loot Chests — Randomized chests with NPC anchors, manual triggers, and virtual client-side blocks.
  • Party System — Built-in lobby with ready/not-ready states. Optional adapters for MMOCore, Parties.
  • Room Editor — Visual in-game room editor with particle edges, node manipulation, and toolbar.

Permissions

Permission	Description
typewriter.dungeon.admin	Administrate dungeons and the room editor.

Dependencies

Extension	Required	Usage
GUI Extension	Required	All menus use the GUI layout system (layoutPool, mainLayoutId). Without it, no menu will open.
Typewriter	Required	Provides the native quest engine and API used by the integration (Ref<QuestEntry>).
PartyExtension	Optional	External party plugin (Parties, MMOCore). Dungeon has a built-in lobby that works standalone.
PlaceholderAPI	Optional	For @Placeholder placeholder resolution in messages.

Architecture

Entries

• Definitions — Dungeon Instance: Rules, costs, and party config. Category: Groups dungeons in menus. Room: Polygon footprint with enter/leave triggers. Room Config: Room set + spawn point. Loot Chest: Randomized reward containers.
  • Actions — Global Menu: Browse all dungeons. Party Menu: Lobby coordination. Enter: Player join logic. Leave: Player exit logic. Close: Shutdown instance. Loot Chest Trigger: Manual chest activation.
  • Facts — InDungeon Fact: Check if player is inside a dungeon. InDungeonInstance Fact: Check specific dungeon.

User guide

Step 1 — Define a Room

Use /dungeon room my_room edit to enter the visual room editor. Place nodes to form a polygon boundary. Save with Lime Dye.

dungeon_room:
  id: "boss_room"
  name: "Boss Arena"
  nodes:
    - {x: 10, y: 64, z: 10}
    - {x: 20, y: 64, z: 10}
    - {x: 20, y: 64, z: 20}
    - {x: 10, y: 64, z: 20}
  priority: 1
  onEnter:
    - "boss_spawn_trigger"

Step 2 — Group Rooms in a Config

dungeon_room_config:
  id: "dungeon_layout"
  name: "Default Layout"
  rooms:
    - "boss_room"
    - "entrance_room"
  spawnPoint:
    x: 15
    y: 65
    z: 15
    world: "dungeon_template"

Step 3 — Define the Dungeon Instance

dungeon_instance:
  id: "ancient_temple"
  name: "Ancient Temple"
  templateWorld: "dungeon_template"
  roomConfigurations:
    - "dungeon_layout"
  minPartySize: 1
  maxPartySize: 4
  cooldownSeconds: 300

Step 4 — Create a Category and Menu

dungeon_category:
  id: "main_dungeons"
  name: "Main Dungeons"
  instances:
    - dungeonInstance: "ancient_temple"
      unlockedItem: STONE_BRICKS
      unlockedName: "<gold>Ancient Temple</gold>"
      unlockedLore:
        - "<gray>Players: {players}/{max}"

dungeon_global_menu:
  id: "dungeon_hub"
  category: "main_dungeons"
  inventoryTitle: "<bold><gold>⚔ Dungeons</gold></bold>"
  layoutPool:
    - id: "main"
      type: simple
      items: []

Step 5 — Trigger the Menu

From any action, command, NPC dialog, or entry trigger:

action:
  type: dungeon_global_menu
  id: "open_dungeons"
  globalMenu: "dungeon_hub"

Or via command: /dungeon global-menu main_dungeons

Commands

Command	Description
/dungeon global-menu <category>	Open the global dungeon browser
/dungeon party-menu <instance>	Open the party lobby for a specific instance
/dungeon room <room> edit	Enter the visual room editor
/dungeon room <room> addvertex	Add node at target block
/dungeon room <room> removevertexat <index>	Remove node by index
/dungeon room <room> save	Save room and exit editor
/dungeon room <room> cancel	Cancel editing

Placeholders

All placeholders use the prefix %typewriter_dungeon_%.

Placeholder	Description
%typewriter_dungeon_players%	Number of players in the current dungeon.
%typewriter_dungeon_attempts%	Total attempts on this dungeon (per-player artifact).
%typewriter_dungeon_completions%	Completion count (per-player artifact).
%typewriter_dungeon_best_time%	Best completion time formatted (per-player artifact).

Troubleshooting

The extension is not visible

Check that the installed release matches the supported TypeWriter release and that the related extensions listed in the compatibility section are present.

An entry is missing

In the Typewriter Web panel, use the Search bar or the + button to find or create the entry with its exact identifier. Entry IDs and field names are case-sensitive; do not translate them.

The entry saves but nothing happens

Check that the entry is connected to the trigger, command, objective, event, or menu interaction required by its type. Test with optional permissions and criteria removed, then add them back one at a time.

An integration does not work

Verify the dependency and version shown in the extension card, then check the server log for the first error. Do not replace a missing dependency with a similarly named plugin unless the extension source explicitly supports it.