> For the complete documentation index, see [llms.txt](https://esmp-fun.gitbook.io/plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://esmp-fun.gitbook.io/plugins/vault-crates/installation.md).

# Installation

## What you need

* A **Paper or Folia** server running Minecraft **1.21.7 or newer**. The plugin uses Paper's Dialog API (added MC 1.21.6, Paper bindings since 1.21.7); older Paper versions will fail to load. All scheduling is region-aware, so it runs natively on Folia.
* Running a **Minecraft 26.x** server? Pick the **26.x** build in the download version picker on your [esmp.fun](https://esmp.fun/plugins) dashboard — the 1.21 jar won't load on 26.x and vice versa (the `api-version` gate is deliberate).
* **Java 21** or newer.
* **BetterTrialChambers v1.4.0+** already installed and working. If you haven't installed it yet, grab it from [Modrinth](https://modrinth.com/plugin/trialchamberpro) — it's free and the install is the same as any plugin.
* **(Optional) LuckPerms** for `/tcpvc reset <crate> group <permission>` offline-player resolution. Without LuckPerms the group reset still works but only covers currently-online players.

## Step 1 — Drop in the JAR

Copy the `tcp-vault-crates-<version>.jar` you downloaded into your server's `plugins/` folder. Don't rename the file — its name is what the server uses to find it.

You'll have something like this:

```
plugins/
├── BetterTrialChambers-1.4.x.jar
├── tcp-vault-crates-<version>.jar      ← new
└── ...
```

## Step 2 — Restart the server

Restart (don't reload — `/reload` is unreliable for plugins that register listeners on enable, and you'll get strange behaviour).

## Step 3 — Verify it loaded

Watch the console as the server boots. You should see something like:

```
[INFO] [Vault Crates] License key sourced from JAR placeholder (production distribution).
[INFO] [Vault Crates] Loaded 2 crate type(s).
[INFO] [Vault Crates] Registered KeyDropService — Wild Spawners and other plugins can now drop crate keys.
[INFO] ╔══════════════════════════════════════╗
[INFO] ║  Vault Crates v1.0.0          ║
[INFO] ║  Licensed via ESMP               ║
[INFO] ╚══════════════════════════════════════╝
```

If you see the banner, you're good. The `Loaded 2 crate type(s)` line refers to the example `common` and `legendary` crates that ship with the plugin — feel free to delete or rewrite them in `crates.yml`.

## Step 4 — Confirm the GUI works

Join the server as an op (or anyone with the `tcpvc.admin` permission). Run:

```
/tcpvc gui
```

A paginated chest GUI should open showing the example crates. Click one to enter its editor. If it works, your install is complete.

## What if it didn't load?

If you don't see the banner, check the console for ERROR or SEVERE lines. The most common issues:

* **"BetterTrialChambers not loaded — cannot activate Vault Crates."** BetterTrialChambers is missing or failed to load. Check that you have the free TCP plugin installed at v1.4.0 or later.
* **"License verification FAILED."** The JAR you downloaded didn't receive its embedded licence, OR you're trying to run a licence tied to a different buyer account (licences are tied to your account, not your server, so this is rare). Re-download the JAR from your purchase page at [esmp.fun/plugins](https://esmp.fun/plugins) (or whichever store you bought it from).
* **`ClassNotFoundException` at startup.** Almost always means your Paper version is too old. Update to Paper 1.21.7+.

For anything else, hop into the Discord linked from the product page and we'll sort it out.

## Where the plugin's files live

After first boot, look for:

```
plugins/Vault Crates/
├── config.yml             ← global toggles (bulk-open, holograms, protection)
├── crates.yml             ← your crate definitions
├── messages.yml           ← every player-facing string
└── license-cache.dat      ← 3-day offline grace cache (don't share or commit!)
```

The first three are yours to edit. `license-cache.dat` is managed by the plugin — never copy it between machines or upload it anywhere.

***

Next: [**Your first crate →**](/plugins/vault-crates/your-first-crate.md)