Dungeon

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.
QuestExtension	Required	Runtime dependency for quest 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.

Quick Start 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).