🏰 DungeonForge Documentation

Welcome to the official documentation for DungeonForge - The Ultimate Dungeon Creation System for Minecraft servers.

📦 Installation

Server Requirements

• Server Software: Paper (recommended), Spigot, or CraftBukkit
• Minecraft Version: 1.16 or higher
• Java Version: Java 16+

Installation Steps

1. Stop your server
2. Download DungeonForge-1.0.8.jar (recommended)
3. Place the JAR file in your plugins/ folder
4. Start the server to generate config files
5. (Recommended) Restart after making config changes

Generated Files

plugins/DungeonForge/
├── config.yml          # Main configuration
├── loot_tables.yml     # Loot table definitions
├── dungeons/           # Your dungeon saves
│   └── *.yml
└── templates/          # Room templates (NBT)
    └── <dungeonId>/
        └── *.nbt

Dungeon packs export to plugins/DungeonForge/packs/ (zip). Use /df pack export <dungeon>.

Optional Integrations

⚡ Quick Start (5 Minutes)

Step-by-Step Guide

1. Create a dungeon:

   /df create MyFirstDungeonCopy

2. Start editing:

   /df edit MyFirstDungeonCopy

   Your hotbar now has quick-access builder items!

3. Open Builder Hub:

   /df buildCopy

   Or use the Compass in your hotbar

4. Follow the guided steps:
   • Create Room (select corners first)
   • Place Start Marker
   • Place End Marker
   • Unlock Free Build tools!
5. Publish your dungeon:

   /df publish MyFirstDungeonCopy

6. Test it!

   /dfjoin MyFirstDungeonCopy

7. Set lobby return point:

   /df setspawnoflobbyCopy

🎮 Your First Dungeon Tutorial

Understanding the Builder Flow

DungeonForge uses a guided builder system that walks you through creating a dungeon step by step.

👤 Player Commands

Main command aliases: /dungeonforge, /df, /dungeon, /dungeons

🔨 Builder Commands

Prefab Commands

👥 Party Commands

⚙️ Admin Commands

🪄 Wand System

The wand is your primary building tool. Get one with /df wand or /dfwand.

Wand Types

Wand Modes

Cycle modes with Shift + Drop (Q)

🎒 Builder Hotbar

When you enter edit mode (/df edit <name>), your hotbar is populated with quick-access items:

🏠 Room Creation

Rooms are the building blocks of dungeons. Each room contains markers and can be used as a prefab template.

Creating a Room

1. Enter edit mode: /df edit <dungeon>
2. Get your wand: /df wand
3. Switch to SELECT mode (Shift + Q)
4. Left-click first corner of your room
5. Right-click opposite corner
6. Run: /df room create <roomName>

Room Management

🧱 Prefab System

Prefabs are pre-built room templates you can place instantly. Perfect for quickly building dungeons!

Using Prefabs

1. Open the prefab library: /df prefabs
2. Click a prefab to select it
3. A preview will appear at your location
4. Use commands to position and rotate
5. Confirm placement: /df prefab confirm

Prefab Controls

📍 Core Markers

Core markers define the basic structure of your dungeon.

⚔️ Combat Markers

Combat markers spawn enemies and create challenging encounters.

# Example MythicMobs usage:
mob-type: mm:SkeletonWarrior
count: 5Copy

🎁 Loot Markers

# MMOItems loot example:
items:
  - "mi:SWORD:FLAME_BLADE"
  - "mi:ARMOR:DRAGON_HELM"Copy

🔐 Puzzle Markers

Puzzle markers create interactive challenges that players must solve to progress. DungeonForge supports three puzzle types plus doors and keys.

Puzzle Types

Riddle: "I have cities, but no houses. I have mountains, but no trees. I have water, but no fish. What am I?"
Answer: "map"

Riddle: "The more you take, the more you leave behind. What am I?"
Answer: "footsteps"Copy

Puzzle Rewards

When a puzzle is completed, players receive a reward. Configure the reward type in the marker settings:

Setting Up a Lever Puzzle (Step-by-Step)

1. Enter edit mode: /df edit <dungeon>
2. Get your wand and switch to MARKER mode
3. Place a PUZZLE marker at each lever location
4. Switch to INFO mode and right-click each marker to configure:
   • Set Puzzle Type to "Lever Sequence"
   • Set the same Group ID for all levers (e.g., "lever_puzzle_1")
   • Set Sequence Order: 0 for first, 1 for second, etc.
   • Configure reward on the FIRST marker in the sequence
5. Place actual lever blocks at each marker location
6. Add visual clues (signs, colors, symbols) to hint at the order

Doors & Keys

🧑‍🌾 Villager NPC Markers

Add helpful NPCs to your dungeons! Villager NPCs provide services like healing, shops, and buff stations that players can use during their run.

NPC Service Types

Currency Types

Earning Dungeon Coins

Players earn Dungeon Coins from various activities during their run:

Coins are displayed in the action bar and reset when the dungeon run ends.

Setting Up an NPC (Step-by-Step)

1. Enter edit mode: /df edit <dungeon>
2. Get your wand and switch to MARKER mode
3. Place a VILLAGER_NPC marker where you want the NPC
4. Switch to INFO mode and right-click to configure:
   • Select the Service Type (Healer, Shop, or Buff Station)
   • Configure service-specific options
   • Set the Currency Type and cost
   • Optionally set a cooldown
5. Save and test your dungeon!

⭐ Featured Dungeon System

Create special weekly events with the Featured Dungeon rotation system! Designate dungeons as "featured" for limited time periods with bonus rewards to drive player engagement.

For Players

Access the current featured dungeon:

/df featured           # Open featured dungeon menu
/df menu               # Featured button appears in dungeon listCopy

Featured dungeons are marked with a ⭐ star icon and show "Featured Bonus!" on rewards.

For Admins

featured-dungeons:
  enabled: true
  rotation-duration-hours: 168    # 1 week default
  auto-rotate: true               # Auto-rotate when time expires
  hide-from-regular-list: false   # Hide from regular menu
  separate-leaderboard: false     # Track featured separately

  reward-multipliers:
    exp: 1.5          # 50% more EXP
    money: 1.5        # 50% more money
    loot-quality: 1.25  # 25% better loot

  indicator:
    prefix: "&6⭐ "                      # Name prefix
    lore: "&e&l★ FEATURED DUNGEON ★"   # Item loreCopy

👥 Party System

Team up with friends to tackle dungeons together!

Creating & Managing Parties

1. Create a party: /dfparty create
2. Invite friends: /dfparty invite <player>
3. Friend accepts: /dfparty accept
4. Join dungeon together: /dfjoin <dungeon>

Party Features

• Shared Instance: All party members join the same dungeon instance
• Party Chat: Private communication channel
• Shared Progress: Checkpoints and objectives sync across party
• Loot Distribution: Configurable loot sharing modes

Matchmaking

Solo players can use the matchmaking queue to find parties:

/df queue <dungeon>   # Join the queue
/df queue leave        # Leave the queueCopy

💎 Loot System

DungeonForge features a 5-tier loot system with customizable loot tables.

Loot Tiers

Loot Table Configuration

Edit plugins/DungeonForge/loot_tables.yml to customize loot:

tier_1:
  items:
    - material: IRON_SWORD
      chance: 0.3
      enchantments:
        SHARPNESS: 1
    - material: GOLDEN_APPLE
      amount: 1-3
      chance: 0.5Copy

MMOItems Integration

Add custom MMOItems to loot tables:

tier_5:
  items:
    - mmoitem: "SWORD:LEGENDARY_BLADE"
      chance: 0.1
    - mmoitem: "ARMOR:DRAGON_PLATE"
      chance: 0.05Copy

💀 Boss Fights

Create epic boss encounters with phases, abilities, and health bars!

Boss Features

• Boss Bar: Displays health at top of screen
• Multiple Phases: Boss changes behavior as health drops
• Custom Abilities: Special attacks per phase
• Loot Drops: Guaranteed rewards on defeat

Phase System

Bosses transition through phases based on health percentage:

Phase 1: 100% - 67% health
Phase 2: 66% - 34% health  (abilities unlock)
Phase 3: 33% - 0% health   (enraged mode)Copy

Configuration

boss:
  health-multiplier: 10.0
  damage-multiplier: 2.0
  phases:
    enabled: true
    count: 3
  abilities:
    enabled: trueCopy

🌍 Instancing

Each party gets their own isolated copy of the dungeon!

Instance Types

How Instancing Works

1. Player/party runs /dfjoin <dungeon>
2. DungeonForge creates/assigns an instance
3. Dungeon is copied to the instance
4. Players are teleported in
5. On completion/leave, instance is cleaned up

Instance Protection

• Players cannot break dungeon blocks
• Mob spawning is controlled by markers
• Inventory optionally saved/restored
• Death handling is customizable

Configuration

instances:
  isolated-worlds:
    enabled: true
    world-prefix: "df_instance_"
    delete-on-complete: true
  slot-based:
    enabled: false
    slots-per-dungeon: 5Copy

🎲 Procedural Generation

Generate unique dungeon layouts each run using room templates and connectors!

How It Works

1. Create multiple room templates (prefabs)
2. Add CONNECTOR markers to each room
3. Link connectors with compatible rooms
4. DungeonForge randomly assembles rooms each run

Connector Setup

1. Switch wand to MARKER mode
2. Place CONNECTOR markers at doorways
3. Switch to CONNECT mode
4. Right-click two connectors to link them

Configuration

procedural:
  enabled: true
  min-rooms: 5
  max-rooms: 12
  branch-chance: 0.3
  corridor:
    enabled: true
    min-length: 3
    max-length: 8Copy

📋 General Configuration

Main settings in plugins/DungeonForge/config.yml

general:
  language: en_US
  debug: false

builder:
  default-wand-mode: SELECT
  particles-enabled: true
  selection-particle: FLAME

preview:
  enabled: true
  duration-seconds: 60
  particle-density: 1.0Copy

RPG & Skills HUD

rpg:
  enabled: false           # Master toggle for RPG features
  classes:
    enabled: false         # Enable class system
  skills:
    enabled: false         # Enable skill tree/unlocks
  hud:
    enabled: false         # Enable skills HUD on actionbar
    slots: [0, 1, 2]       # Hotbar slots to show in HUD
    show-in-dungeons: false # Show skills HUD inside dungeon instances

abilities:
  enabled: false           # Enable player ability itemsCopy

🏆 Leaderboards & Timers

DungeonForge can record completion times per dungeon and expose them via commands, GUI, and PlaceholderAPI.

Public access

To make leaderboards public (players can view via /df leaderboard, /dfleaderboard, and the main menu button):

leaderboards:
  enabled: true
  public-command-enabled: true
  # Optional permission gate for players:
  # dungeonforge.leaderboardCopy

File size control

The file plugins/DungeonForge/leaderboards.yml grows based on how many dungeons and players you keep. Use these caps to keep it bounded.

leaderboards:
  # Keep only the fastest N player best-times per dungeon (0 = unlimited)
  max-best-per-dungeon: 500
  # Keep last N successful runs per dungeon (0 = disable history)
  max-history-per-dungeon: 100Copy

🌐 Instance Configuration

instances:
  isolated-worlds:
    enabled: true
    world-prefix: "df_instance_"
    delete-on-complete: true
    ground-level-placement:
      enabled: true
      target-y: 64

  slot-based:
    enabled: false
    slots-per-dungeon: 5
    slot-spacing: 1000

  protection:
    prevent-block-break: true
    prevent-block-place: true
    prevent-mob-spawning: true

  player:
    save-inventory: true
    restore-on-leave: true
    teleport-on-death: CHECKPOINTCopy

📍 Marker Default Configuration

markers:
  defaults:
    mob_spawn:
      type: ZOMBIE
      count: 4
      level: 1
      radius: 3.0
      respawn: 30

    boss_spawn:
      type: WITHER_SKELETON
      name: "Dungeon Boss"
      health: 200.0
      # Boss key drop settings
      drop-key:
        enabled: false
        key-lock-id: "BOSS"
        key-name: "Boss Key"
        key-material: "TRIPWIRE_HOOK"
        give-to-players: true

    wave_spawner:
      waves: 3
      mobs_per_wave: 5
      delay: 10

    loot_chest:
      tier: 1
      chest-type: CHEST
      item-count: 5

    door:
      lock-id: "A"
      locked: true
      consume-key: true

    key_location:
      lock-id: "A"
      name: "Rusty Key"
      material: "TRIPWIRE_HOOK"Copy

🎁 Loot Configuration

loot:
  enabled: true

rewards:
  economy:
    enabled: true
    base-amount: 100
    per-tier-bonus: 50
  experience:
    enabled: true
    base-xp: 50

drops:
  mobs:
    enabled: true
    drop-chance: 0.3
  bosses:
    guaranteed-drops: true
    drop-count: 3Copy

👹 MythicMobs Integration

Spawn custom MythicMobs creatures in your dungeons!

Usage

Prefix mob names with mm: in any spawner marker:

# MOB_SPAWN marker
mob-type: mm:SkeletonWarrior

# BOSS_SPAWN marker
boss-type: mm:DragonLord

# WAVE_SPAWNER marker
mob-types:
  - mm:Zombie
  - mm:SkeletonArcher
  - mm:DarkMageCopy

Requirements

• MythicMobs 5.x installed and configured
• Mob must be defined in MythicMobs config

⚔️ Elite Mob Types

DungeonForge includes built-in elite mob variants with enhanced stats and special abilities. No external plugins required!

Default Elite Mobs

Usage

Use elite mob IDs in any MOB_SPAWN or WAVE_SPAWNER marker:

# In marker configuration
mob-type: elite_brute

# Or in wave spawner
mob-types:
  - elite_assassin
  - elite_shaman
  - ZOMBIECopy

Custom Elite Configuration

Define your own elite mobs in config.yml:

mobs:
  elites:
    elite_tank:
      base-type: IRON_GOLEM
      display-name: "&4Tank"
      size: 1.8
      speed: 0.5
      health-multiplier: 3.0
      damage-multiplier: 0.8
      ability: resistance
    elite_ninja:
      base-type: ENDERMAN
      display-name: "&5Ninja"
      size: 0.9
      speed: 2.0
      health-multiplier: 0.6
      damage-multiplier: 2.0
      ability: invisibleCopy

Available Abilities

🗡️ MMOItems Integration

Add custom MMOItems to loot chests and drop tables!

Usage

Prefix items with mi:TYPE:ID in loot tables:

tier_5:
  items:
    - mmoitem: "SWORD:FLAME_BLADE"
      chance: 0.1
    - mmoitem: "ARMOR:DRAGON_HELM"
      chance: 0.05
    - mmoitem: "CONSUMABLE:HEALTH_POTION"
      chance: 0.3Copy

Marker Configuration

In LOOT_CHEST marker config:

items:
  - "mi:SWORD:LEGENDARY_BLADE"
  - "mi:ARMOR:DRAGON_PLATE"
  - "mi:GEM:FIRE_RUBY"Copy

Requirements

• MMOItems installed and configured
• Items must exist in MMOItems database

🔌 Other Plugin Integrations

Vault (Economy)

Reward players with money on dungeon completion:

rewards:
  economy:
    enabled: true
    base-amount: 100
    per-tier-bonus: 50Copy

PlaceholderAPI

DungeonForge can register a PlaceholderAPI expansion (disabled by default).

Enable it:

integrations:
  placeholderapi:
    enabled: trueCopy

Then restart the server (or run /df reload).

Available placeholders:

Webhooks

DungeonForge can send JSON webhooks on publish and on run end (disabled by default).

Enable it:

integrations:
  webhooks:
    enabled: true
    urls:
      - "https://your-webhook-url"
    events:
      publish: true
      run_end: trueCopy

Citizens (NPCs)

Place Citizens NPCs in dungeons for quests or merchants. NPCs persist in templates and are cloned to instances.

ModelEngine

Apply custom models to mobs spawned by MythicMobs integration. Models display correctly in dungeon instances.

🔑 Permissions

Permission Hierarchy

dungeonforge.admin
  - dungeonforge.build
  - dungeonforge.leaderboard
  - dungeonforge.play
  - dungeonforge.partyCopy

🔧 Troubleshooting

❓ Frequently Asked Questions

🗺️ Roadmap

DungeonForge is built to feel like a premium dungeon platform, not just a “dungeon plugin”. This roadmap is the vision for where we’re taking it next — bigger content systems, smoother building, and more “MMO server” polish.

Want to influence the roadmap?

Join the Discord, share your server goals, and tell us what “premium” means for your community — we build the features that make servers feel legendary.

🏰 DungeonForge

The Ultimate Dungeon Creation System

Made with ❤️ for Minecraft

Back to Top