# Installation

## 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.
* **Java 21** or newer.
* **TrialChamberPro 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-1.0.0.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/
├── TrialChamberPro-1.4.x.jar
├── tcp-vault-crates-1.0.0.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] [TCP-VaultCrates] License key sourced from JAR placeholder (production distribution).
[INFO] [TCP-VaultCrates] Loaded 2 crate type(s).
[INFO] [TCP-VaultCrates] Registered KeyDropService — TCP-WildSpawners and other plugins can now drop crate keys.
[INFO] ╔══════════════════════════════════════╗
[INFO] ║  TCP-VaultCrates 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:

* **"TrialChamberPro not loaded — cannot activate TCP-VaultCrates."** TrialChamberPro 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 license, OR you're trying to run a license tied to a different server (ESMP & Voxel ties licenses to your account, not your server, so this is rare). Re-download the JAR from <https://esmp.fun/plugins>.
* **`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/TCP-VaultCrates/
├── config.yml             ← global toggles (bulk-open, holograms, protection)
├── crates.yml             ← your crate definitions
├── messages.yml           ← every player-facing string
├── polymart.properties    ← embedded license key (don't share!)
└── license-cache.dat      ← 3-day offline grace cache (don't share or commit!)
```

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

***

Next: **Your first crate →**


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://darkstarworks.gitbook.io/plugins/mc/tcp-documentation/tcp-vaultcrates/installation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.