Getting Started

Welcome to PhantomDungeons! This guide will walk you through the installation and basic setup process.

---

Installation Guide

Step 1: Download & Install

1

Download the Plugin JAR

Download the latest version of PhantomDungeons from your provider (currently only BuiltByBit)

• File name: PhantomDungeons-x.x.x.jar

2

Place in Plugins Folder

Navigate to your server directory and place the JAR file in the plugins/ folder.

server/
├── plugins/
│   ├── PhantomDungeons.jar  ← Place here
│   └── (other plugins)
├── world/
└── (other files)

3

Verify Dependencies (Crucial)

Ensure your server has the required plugins installed:

• PlaceholderAPI (v2.11.0+) - For placeholder support.

• Paper/Purpur Server (1.21.0+)

• PacketEvents (2.11.1+) - For packet support.

Download PlaceholderAPI: https://www.spigotmc.org/resources/placeholderapi.6245/

Download PacketEvents: https://modrinth.com/plugin/packetevents

4

Start the Server

Restart your server to load the plugin.

./start.sh

Check console for:

[PhantomDungeons] Enabling PhantomDungeons v1.0
[PhantomDungeons] PhantomDungeons enabled successfully!

---

First Time Setup

Step 2: Initial Configuration

1

Auto-Generated Folders

After first startup, the plugin automatically creates:

plugins/PhantomDungeons/
├── config.yml              ← Main settings
├── database.yml            ← Database settings
├── modules.yml             ← Sub-Module settings
├── sword.yml               ← Sword settings
├── database.db             ← Player data storage
├── economies/              ← Currency configs
│   ├── money.yml
│   └── sword-xp.yml
├── zones/                  ← Zone definitions
├── mobs/                   ← Mob configs
├── enchants/               ← Enchantment configs
├── menus/                  ← UI inventory layouts
├── boosters/               ← Booster item configs
└── levels/                 ← Leveling system configs

2

Edit Main Config

Open plugins/PhantomDungeons/config.yml and insert your License Key which can you get from joining and verifying in our discord here.

config.yml

License-Key: "YOUR_LICENSE_KEY_HERE" ## Example XXXX-XXXX-XXXX-XXXX

No database setup needed - SQLite works out of the box

3

All changes are now live.

---

Creating Your First Zone

Step 3: Build a Dungeon Zone

1

Get the Selection Wand

In-game, as an OP/Admin:

/dadmin wand

You'll receive a wooden axe for zone bounds selection.

2

Selecting Zone Bounds

• Left-click a block at the corner of your zone area

  • Message: Position 1 set

• Right-click the opposite corner

  • Message: Position 2 set

The area between these two corners is your zone.

3

Creating the Zone

When you are done selecting your zone, type the following command to create it:

/dadmin createzone my-zone 1

This creates:

• Zone ID: my-zone - Zone ID

• Starting Stage: 1 - Starting stage number

Check console for any errors, if there are ANY errors in this stage, please open a ticket.

4

Marking Spawn Locations

Before mobs can spawn, you must mark spawn locations. Get the location marking wand:

/dadmin locationwand

Then right-click blocks in your zone where you want mobs to spawn:

• Each right-click adds a spawn location

• You need at least as many locations as max-mobs value

• For example, if max-mobs: 20, mark at least 20 different locations

5

Configuring Zone Settings

Edit plugins/PhantomDungeons/zones/my-zone.yml:

metadata:
  world: "world"  # World name where zone is located
  zone-id: "my-zone"
  
max-mobs: 20  # Maximum mobs in zone simultaneously
mob-respawn-time: 100  # Ticks until respawn after kill

stages:
  '1':
    mobs:
      '1':
        mob: chicken-common
        chance: 0.7  # 70% spawn chance
      '2':
        mob: chicken-rare
        chance: 0.3  # 30% spawn chance

# Auto-populated from your location wand marks:
locations:
  - "-100.5,64.0,-200.5"
  - "-105.5,64.0,-205.5"
  - "-110.5,64.0,-210.5"
  # ... more locations (at least 20 total)

Key points:

• chance values should total 1.0 (100%)

• Each mob type references a mob config file (must exist in mobs/ folder)

• Spawn locations are auto-added when using location wand

• More locations = better mob distribution

---

Understanding the Core Systems

Economies (Currencies)

Currencies like Money, Sword XP, and Souls are managed separately:

/money balance          ← Check your balance
/money transfer [player] [amount]  ← Send money

Add new currencies by creating files in economies/ folder.

---

Levels & Progression

Players gain experience in multiple systems:

• Sword XP - From hitting mobs, levels your sword

• Zone Progress - Stages unlock as you complete objectives

---

Next Steps

• Create More Zones - Repeat the Create a Dungeon Zone steps for additional dungeons

• Customize Mobs - Edit mob configs for unique variants

• Build Menus - Create GUIs in menus/ folder

• Add Boosters - Create temporary multiplier items

• Script Enchants - Design custom enchantment effects

---

Common Commands

Command	Permission	Purpose
/money balance	phantomdungeons.economy	Check balance
/sword info	phantomdungeons.sword	View sword stats
/testdung:dungeon reload	phantomdungeons.admin	Reload configs
/testdung:dungeonadmin setzone <player> <zone>	phantomdungeons.admin	Assign player to zone
/papi parse me %phantomdungeons_sword_tier%	Any	View placeholders

---

Troubleshooting

"Plugin failed to load"

• Check that PlaceholderAPI is installed

• Verify server version is 1.21+

• Check console for error messages

"Mobs won't spawn"

• Ensure spawn locations are set in zone config

• Verify mob config files exist in mobs/ folder

• Check player has correct zone assignment

"Commands not working"

• Verify you have admin permissions

• Use full command: /testdung:dungeon instead of /dungeon

• Check plugin loaded: /plugins

"Invalid License Key"

• Verify that the license key is correct.

• Default license keys come with 1 IP allowance, if you are running it on multiple servers (i.e. dev server) please open a ticket and we can add more.

• Check that your machine has a stable connection

If none of these tips resolved your issue, please join our discord server and open a ticket.

---

Support & Resources

• Documentation: Check the wiki for detailed guides

• Config Examples: All .yml files have comments explaining each field

• API Access: Developers can use EconomyAPI, BoosterAPI, and EnchantAPI and various other APIs to create external systems.

---

Ready to dive in? Start by creating your first zone.