Skip to main content
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.

​
Dependencies

ExtensionRequiredUsage
GUI ExtensionRequiredAll menus use the GUI layout system (layoutPool, mainLayoutId). Without it, no menu will open.
QuestExtensionRequiredRuntime dependency for quest integration (Ref<QuestEntry>).
PartyExtensionOptionalExternal party plugin (Parties, MMOCore). Dungeon has a built-in lobby that works standalone.
PlaceholderAPIOptionalFor @Placeholder placeholder resolution in messages.

​
build.gradle.kts Setup

// REQUIRED: GUI Extension (menu rendering)
implementation(files("../Typewriter-GUIExtension/build/libs/Typewriter-GUIExtension-0.1.0.jar"))

// REQUIRED: Quest Extension (runtime)
implementation("com.typewritermc:QuestExtension:0.9.0")

// REQUIRED: Paper API (compileOnly — provided by server)
compileOnly("io.papermc.paper:paper-api:1.21.4-R0.1-SNAPSHOT")

// typewriter { extension { } } block
typewriter {
    extension {
        dependencies {
            dependency("typewritermc", "Quest")
        }
    }
}

​
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

CommandDescription
/dungeon global-menu <category>Open the global dungeon browser
/dungeon party-menu <instance>Open the party lobby for a specific instance
/dungeon room <room> editEnter the visual room editor
/dungeon room <room> addvertexAdd node at target block
/dungeon room <room> removevertexat <index>Remove node by index
/dungeon room <room> saveSave room and exit editor
/dungeon room <room> cancelCancel editing

​
Placeholders

All placeholders use the prefix %typewriter_dungeon_%.
PlaceholderDescription
%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).