# DungeonInstances<\/p>\n
A Spigot\/Paper Minecraft plugin for managing instanced dungeons with party system, clickable invitations, admin commands and in-game scoreboard HUD.<\/p>\n
—<\/p>\n
## Overview<\/p>\n
**DungeonInstances** lets you create dungeon worlds copied from templates, invite players to parties, and display a dynamic scoreboard when inside an instance. The plugin aims for simple administration (create\/delete\/edit templates, set spawns) and friendly UX (colored messages, clickable buttons to accept\/decline invitations).<\/p>\n
## Main Features ## Installation<\/p>\n 1. Build:<\/p>\n “`bash Or use the `.\/build` script if you made it executable.<\/p>\n 2. Deploy: copy the generated JAR to your Spigot\/Paper server’s `plugins\/` folder:<\/p>\n “`bash 3. Restart the server.<\/p>\n ## Important Folder Structure ## Commands<\/p>\n All commands are under `\/dungeon`.<\/p>\n – `\/dungeon instance [difficulty]` – `\/dungeon leave` – `\/dungeon list` – `\/dungeon admin ` (requires permission: `dungeon.admin`) – `\/dungeon party ` Notes: ## Scoreboard (HUD)<\/p>\n – The scoreboard activates automatically for players in a world whose name starts with `instance_`. ## Spawn Points<\/p>\n – Set a spawn per template with:<\/p>\n “` – Spawns are persisted in `plugins\/DungeonInstances\/spawnPoints.json`.<\/p>\n ## Templates & Instances<\/p>\n – Place your dungeon templates in `templates-dungeons\/ ## Permissions<\/p>\n – `dungeon.admin` \u2013 access to admin commands (`\/dungeon admin …`).<\/p>\n Other commands have no specific permissions by default (you can add checks if needed).<\/p>\n ## Troubleshooting<\/p>\n – If an instance fails to load, check write permissions on the world container folder (template folder copy). ## Custom Loot Tables<\/p>\n DungeonInstances includes a loot table system per dungeon\/difficulty. Each mob can be marked with a **pool alias** that determines the loot table used when the mob dies in an instance. The alias is stored in NBT (PersistentDataContainer) and persists across saves\/loads.<\/p>\n ### Configuration<\/p>\n The config file is at `plugins\/DungeonInstances\/lootTables.json`. On first load, an empty `{}` is created so admins can populate it manually. Expected structure:<\/p>\n “`json Complete example for template `manaria` with `default` alias across all four difficulties:<\/p>\n “`json In this example, increasing difficulty raises both `iterations` and drop chances; adjust these values to suit your needs.<\/p>\n ### Loot Table Fields<\/p>\n – `iterations` \u2013 number of times the pool is visited; each iteration randomly picks an item from `loots`. ### Assigning Aliases<\/p>\n While editing a template, look at a mob and run:<\/p>\n “` The plugin shows the current alias if no argument is given. To clear the alias, use `none`:<\/p>\n “` The alias is saved with the mob and automatically restored in instances.<\/p>\n ### Reloading Configuration<\/p>\n After editing `lootTables.json` on disk, reload changes in-game with:<\/p>\n “` ### In-Game Behavior<\/p>\n When a mob with an alias dies in an instance, vanilla drops are removed and replaced with items calculated from the matching pool (template + difficulty + alias). If no table is found, vanilla behavior is unchanged.<\/p>\n ## Customization & Suggestions<\/p>\n – You can modify the scoreboard update frequency (`DungeonScoreboardManager`) and message formats in the code. A plugin that help with creating WoW like dungeons<\/p>\n","protected":false},"featured_media":23958,"template":"","meta":{"_minecraft_slug":"dungeoninstances","_minecraft_project_id":"ZHmOTZF8","_minecraft_author":"fox3000foxy","_minecraft_license":"Apache-2.0","_minecraft_downloads":87,"_minecraft_follows":2,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"dungeoninstances.zip","_minecraft_size_bytes":13063780,"_minecraft_version_count":3,"_minecraft_updated_at":"2026-05-15T20:06:16.596575Z","_minecraft_date_created":"2026-02-28T02:43:13.822388Z","_minecraft_date_modified":"2026-02-24T13:43:18.830143Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/dungeoninstances","_minecraft_icon_attachment_id":23958,"_minecraft_imported_at":"2026-06-03T06:25:02+00:00","_minecraft_import_hash":"214f56df4ffcfd50919ff61c617c0065","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[87,124,88,89,866,137,127,128,129,159],"mod_loader":[130,132,133,134],"minecraft_version":[54,55,56,57,58,62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-59648","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-adventure","mod_category-bukkit","mod_category-equipment","mod_category-game-mechanics","mod_category-minigame","mod_category-mobs","mod_category-paper","mod_category-purpur","mod_category-spigot","mod_category-worldgen","mod_loader-bukkit","mod_loader-paper","mod_loader-purpur","mod_loader-spigot","minecraft_version-1-19","minecraft_version-1-19-1","minecraft_version-1-19-2","minecraft_version-1-19-3","minecraft_version-1-19-4","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n– Instance creation based on templates (folders under `templates-dungeons\/`).
\n– Party system with clickable invitations (`[Accept]`, `[Decline]`).
\n– Admin commands: load\/edit\/save\/purge instances, define spawn points.
\n– Scoreboard visible in instance worlds (`instance_
\n – Party members (leader marked with `\u265b`, you marked with `\u2605`).
\n – Directional arrows showing members’ relative position.
\n – Current health in color (green\/yellow\/red).
\n – Offline members displayed with strikethrough.<\/p>\n
\ncd \/path\/to\/DungeonsInstances
\nmvn clean package -DskipTests -T 1C
\n“`<\/p>\n
\ncp “target\/Dungeon Instances-1.0.0.jar” \/path\/to\/server\/plugins\/
\n“`<\/p>\n
\n– `templates-dungeons\/` \u2013 template folders (one folder = one dungeon template). If the folder doesn’t exist, the plugin automatically creates it and installs the default *manaria* dungeon from its internal archive.
\n– `plugins\/DungeonInstances\/spawnPoints.json` \u2013 spawn points set via `\/dungeon admin setspawn`.<\/p>\n
\n – Creates an instance from the template with one of these difficulty levels: **Beginner**, **Normal** (default), **Heroic**, **Mythic**.
\n Difficulty applies multipliers to creature health, damage and armor.
\n – The player (party leader) and members receive a message and are teleported after a few seconds.<\/p>\n
\n – Leaves the instance and restores normal state.<\/p>\n
\n – Lists available templates and\/or active instances.<\/p>\n
\n – `edit ` \u2013 creates\/opens an edit instance for a template.
\n – `save
\n – `purge
\n – `setspawn ` \u2013 registers your current position as spawn for this template (saved in `spawnPoints.json`).
\n – `alias
\n – `reloadloot` \u2013 reloads loot tables from `lootTables.json`.<\/p>\n
\n – `create [name]` \u2013 creates a new party. If no name is given, the plugin uses the creator’s username (spaces replaced with underscores). Names must be unique \u2014 creation fails if the name exists.
\n – `invite
\n – `accept` \u2013 accepts the last invitation. Automatically leaves any existing party before joining the new one.
\n – `decline` \u2013 declines the last invitation.
\n – `leave` \u2013 leaves the party. If the player is in an instance (`instance_…`), they are teleported to their previous world (if known) or main spawn.
\n – `kick
\n – `disband` \u2013 (leader only) dissolves the group \u2014 notifies all members, clears pending invitations and teleports members in instances to their previous world.
\n – `list` \u2013 lists parties\/members.
\n – `members` \u2013 shows party members (Leader\/You, online\/offline).<\/p>\n
\n– Invitations use TextComponent API to provide clickable buttons on the client.
\n– Admin commands are hidden from players without permission.<\/p>\n
\n– It displays in the sidebar:
\n – The dungeon name (extracted from world name `instance_
\n – Party members with health status, relative direction, leader\/star markers.
\n – Uniform separators (header\/footer) in consistent color.<\/p>\n
\n\/dungeon admin setspawn
\n“`<\/p>\n
\n– Instances are created by copying and loaded under `instance_
\n– Empty instances are automatically unloaded and deleted.<\/p>\n
\n– If the scoreboard doesn’t appear: ensure you’re in an `instance_…` world and belong to a party.
\n– If offline player names display incorrectly, the plugin uses `Bukkit.getOfflinePlayer(UUID).getName()` as fallback.<\/p>\n
\n{
\n “
\n “
\n “
\n “iterations”:
\n “loots”: [
\n {
\n “item”: “minecraft:diamond_sword”,
\n “nbt”: { “item_name”: “Legendary Sword” },
\n “count”: 1,
\n “chance”: 0.1
\n },
\n {
\n “item”: “minecraft:iron_nugget”,
\n “nbt”: { “item_name”: “Shield” },
\n “count”: 1,
\n “chance”: 0.4
\n }
\n ]
\n }
\n }
\n }
\n}
\n“`<\/p>\n
\n{
\n “manaria”: {
\n “BEGINNER”: {
\n “default”: {
\n “iterations”: 2,
\n “loots”: [
\n {“item”:”minecraft:emerald”,”nbt”:{},”count”:1,”chance”:0.2},
\n {“item”:”minecraft:gold_nugget”,”nbt”:{},”count”:2,”chance”:0.5}
\n ]
\n }
\n },
\n “NORMAL”: {
\n “default”: {
\n “iterations”: 3,
\n “loots”: [
\n {“item”:”minecraft:emerald”,”nbt”:{},”count”:1,”chance”:0.4},
\n {“item”:”minecraft:gold_ingot”,”nbt”:{},”count”:1,”chance”:0.25},
\n {“item”:”minecraft:iron_nugget”,”nbt”:{},”count”:3,”chance”:0.6}
\n ]
\n }
\n },
\n “HEROIC”: {
\n “default”: {
\n “iterations”: 4,
\n “loots”: [
\n {“item”:”minecraft:diamond”,”nbt”:{},”count”:1,”chance”:0.05},
\n {“item”:”minecraft:gold_ingot”,”nbt”:{},”count”:2,”chance”:0.4},
\n {“item”:”minecraft:iron_ingot”,”nbt”:{},”count”:5,”chance”:0.8}
\n ]
\n }
\n },
\n “MYTHIC”: {
\n “default”: {
\n “iterations”: 5,
\n “loots”: [
\n {“item”:”minecraft:nether_star”,”nbt”:{},”count”:1,”chance”:0.01},
\n {“item”:”minecraft:diamond”,”nbt”:{},”count”:2,”chance”:0.2},
\n {“item”:”minecraft:gold_ingot”,”nbt”:{},”count”:4,”chance”:0.5}
\n ]
\n }
\n }
\n }
\n}
\n“`<\/p>\n
\n– `loots` \u2013 array of possible entries. For each entry, `chance` is compared to a random value (`0.0`\u2013`1.0`); if the roll succeeds, the item is added to drops.
\n– `item` \u2013 Bukkit\/Spigot material ID (`DIAMOND_SWORD`, `IRON_NUGGET`, etc.).
\n– `nbt` \u2013 free mapping for item name (`item_name`), lore, etc. Only simple keys are supported currently (see source code).
\n– `count` \u2013 quantity of items to generate when the entry is selected.<\/p>\n
\n\/dungeon admin alias
\n“`<\/p>\n
\n\/dungeon admin alias none
\n“`<\/p>\n
\n\/dungeon admin reloadloot
\n“`<\/p>\n
\n– Possible improvements: multi-language support, config via `config.yml`, options to hide certain HUD elements.<\/p>\n","protected":false},"excerpt":{"rendered":"