Instanced Dungeons Kits Addon

DungeonKit

DungeonKit is a Paper plugin that adds a complete kit system with in-run upgrades and completion rewards to instanced dungeons. Admins save any loadout as a reusable kit, players pick their kit from a clean GUI, and the kit is applied automatically when a dungeon run begins. Along the way players can power up their gear at upgrade stations and claim rewards when they clear the dungeon.

Features

• Kit System — Save any inventory as a named kit (kits.yml) and give it to players instantly.
• ️ Kit Selection GUI — Players browse available kits in a chest menu with item lore previews of each loadout.
• ⚔️ In-run Upgrades — Upgrade stations raise a random existing enchantment by one level (respecting vanilla max levels), once per station per run.
• Completion Rewards — Reward players with money (Vault), items, or console commands — once per dungeon run (delayed until there in a defined world where inventory/economy keeps).
• Trigger Blocks — Bind any block to act as a kit dispenser or an upgrade station with a single command.
• ️ Per-dungeon Control — Enable or disable kits per dungeon ID in dungeons.yml.
• Live Reload — Reload configuration files without restarting the server.
• Vault Economy Support — Optional money rewards for Vault-based economies.

Requirements

• A Minecraft Paper server (or compatible fork) running 26.1.2
• Java 21+
• (Optional) Vault + an economy plugin, for money rewards
• Built to work alongside an instanced-dungeons plugin that creates per-run worlds (world names ending in an 8-character instance suffix, e.g. amphitheatre_a1b2c3d4)

Installation

1. Ensure https://modrinth.com/plugin/instanced-dungeon is installed on the same 26.1.2 version
2. Download the latest DungeonKit jar.
3. Drop the jar into your server's plugins/ folder.
4. Restart the server.The plugin creates its data folder at plugins/DungeonKit/.
5. (Optional) Install Vault and an economy plugin if you want money rewards.

Setup

All configuration lives in plugins/DungeonKit/. The plugin generates its config files automatically on first start.

1. Create your kits

Have an admin equip the loadout to save (armor, weapons, tools, potions, food, etc.), then run:

/dkitsave <kitname>

The inventory is stored in kits.yml and immediately becomes available in the kit menu. Armor is restored to the correct slots when a kit is applied.

1. Enable dungeons (dungeons.yml)

List each dungeon by its dungeon ID (the world name without the trailing instance suffix) and set enabled:

dungeons:
  amphitheatre:
    enabled: true
  gladiator_pit:
    enabled: false

1. Configure rewards (rewards.yml)

Define reward keys and hand them out via commands or triggers. Three reward types are supported — money (requires Vault), items, and console commands:

rewards:
  default:
    type: MONEY
    amount: 500
  hardmode:
    type: ITEM
    item: NETHERITE_INGOT
    qty: 1
  bossclear:
    type: COMMAND
    cmd: "give %player% diamond 3"

1. (Optional) Place trigger blocks

Look at the block you want to use, then run one of:

• /dkittrigger <kitname> — right-clicking the block gives that kit
• /dkittrigger upgrade — right-clicking the block upgrades a random enchanted item

Trigger bindings are saved in triggers.yml.

1. Wire up auto-kits and auto-rewards (InstancedDungeons)

In each dungeon's commands.yml (inside your dungeon plugin's folder), first make sure the custom commands section is enabled at the top of the file. Then add both hooks:

Auto-kit — fires when a run starts and players enter the instance:

commands:
  - event: on-player-start-dungeon-command
    executor: CONSOLE
    audience: NONE
    run:
      - "dkitgive"

Auto-reward — fires when the dungeon is completed:

  - event: on-player-complete-dungeon-command
    executor: CONSOLE
    audience: NONE
    run:
      - "dkitreward <dungeon_name> <player>"

<dungeon_name> is the dungeon's name (used as the reward key) and <player> is the completing player. The reward is paid after a short 5-second buffer, so the player is back in the main lobby with their real inventory/economy.

Commands

Command	Description	Permission
/dkitsave <kitname>	Save your current inventory as a permanent kit	dungeonkits.admin
/dkitgive <kitname>	Give/apply a kit (console with no args distributes kits to players in enabled dungeons)	dungeonkits.admin
/dkitmenu	Open the kit selection GUI	dungeonkit.player
/dkitupgrade <buttonId>	Upgrade a random enchanted item in your kit	dungeonkits.admin
/dkitreward <rewardKey>	Claim a dungeon completion reward	dungeonkits.admin
`/dkittrigger <kitname	upgrade>`	Bind the block you are looking at as a trigger
/dkitreload	Reload kits.yml and playerkits.yml	dungeonkits.admin
/dungeonreload	Reload dungeons.yml	dungeonkits.admin

Permissions

• dungeonkits.admin — access to all admin commands (default: op)
• dungeonkit.player — allows players to open the kit menu (default: all players)

Tip: Keep dungeonkits.admin for staff only. dungeonkit.player is granted to everyone by default, but can still be overridden per-player or per-group with a permissions plugin (e.g. LuckPerms).

How to Use

1. Admins save kits with /dkitsave, enable dungeons in dungeons.yml, and define rewards in rewards.yml.
2. Players open the kit menu with /dkitmenu and click a kit to select it. Their choice is saved and persists across sessions.
3. When a dungeon run starts, the player's chosen kit is applied automatically. Hook your dungeon plugin's start event to run /dkitgive from the console (no arguments) to distribute kits to every player in enabled dungeon worlds. Players who haven't chosen a kit receive the first available kit.
4. Players interact with upgrade trigger blocks to improve a random enchanted item — once per station, per run.
5. On completion, players claim their reward via /dkitreward <rewardKey> (or a trigger/command hook) — once per run.

Notes

• Upgrades and reward claims are per-instance and reset when the run ends.
• Kit choices are saved per player and persist across sessions and restarts.
• The %player% placeholder is available in command rewards.
• Money rewards require Vault and a compatible economy plugin; they are skipped automatically if Vault is not installed.