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.

2. Enable dungeons (`dungeons.yml`)

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

```yaml
dungeons:
amphitheatre:
enabled: true
gladiator_pit:
enabled: false
```

3. 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:

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

4 . (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

5. 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:

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

**Auto-reward** — fires when the dungeon is completed:

```yaml
- 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.

Trigger bindings are saved in `triggers.yml`.

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 | `dungeonkits.admin` |
| `/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.