> 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/managing-keys.md).

# Managing keys

Crate keys are the link between "player did something to earn a reward" (bought from your shop, killed a wild-spawner mob, completed a quest) and "player gets to open a vault." This page covers everything about issuing, integrating, and recognising keys.

## What a key actually is

A crate key is a regular ItemStack with two PDC tags:

* `tcpvc:crate_id` — the id of the crate this key is bound to (e.g. `common`, `legendary`).
* `tcpvc:key_tier` — `normal` or `ominous`.

The visible material, display name, lore, and custom-model-data come from the `key:` block in `crates.yml`. Two keys of the same crate but different tiers will look different, sound different, and roll different loot.

The PDC tags are what the open flow checks — display name and lore are cosmetic. A player who renames their key in an anvil keeps it working. A player who somehow gets a regular Amethyst Shard with the same display name **doesn't** — it lacks the PDC tag.

### Key-driven tier matching

Which tier rolls is determined by the **held key's PDC tier**, not by the vault block's vanilla ominous state. Both keys can open the same vault as long as both tiers are configured on the crate. When a vault is registered via `/tcpvc set`, the plugin aligns its vanilla `ominous` BlockData flag to match the configured tier(s):

* Only normal tier configured → vault forced non-ominous (cosmetic).
* Only ominous tier configured → vault forced ominous (cosmetic).
* Both tiers configured → vault keeps whatever state the admin placed the block in. Both keys work regardless.

## Issuing keys manually

```
/tcpvc key give <player> <crate> [tier] [amount]
```

Examples:

```
/tcpvc key give Steve common                  → 1 normal key (auto-tier when only one configured)
/tcpvc key give Steve common normal 5         → 5 normal keys
/tcpvc key give Steve legendary ominous       → 1 ominous Legendary key
```

If the crate has both tiers configured, `[tier]` is required. If only one tier is configured, it's optional and the configured tier is used.

## Issuing keys to every online player

```
/tcpvc key give-all <crate> [tier] [amount]
```

Useful for events:

```
/tcpvc key give-all common normal 1
```

Hands one Common Key to every player currently online. Inventory-full players get their key dropped at their feet (no owner-lock for the give command — that's only for vault loot drops).

## Integrating with shop plugins

Most shop plugins (CMI, EssentialsX, custom CommandPanels, Tebex, etc.) work with simple console commands. Any of these will work as a "buy 5 Common Keys" payout:

```
tcpvc key give {player} common normal 5
```

Replace `{player}` with whatever placeholder your shop plugin uses for the buying player's name. For Tebex this is `{player_name}`; for EssentialsX shops it's typically just the player's name (the plugin substitutes when the command runs as `console`).

### Tebex example

In your Tebex package's command list:

```
tcpvc key give {username} legendary ominous 1
```

That's it — the buyer gets a Legendary Key the moment their payment clears.

### Tied-to-purchase example

Want a key to be flagged as "ominous Common" and given via a custom command of your own? Run the same command from any context that has console access:

```kotlin
Bukkit.dispatchCommand(Bukkit.getConsoleSender(), "tcpvc key give Steve common normal 1")
```

## Editing a key's appearance — the Modify Key wizard

From `/tcpvc gui` → click the crate → click the tier's key button. Then click **Modify Key** (writable book) to open a Dialog with three fields:

* **Display name** — MiniMessage supported.
* **Lore** — multi-line, one line per row, MiniMessage supported.
* **Resource-pack model ID** — slider; 0 means "no model id" (vanilla appearance).

Three buttons: **Apply**, **Preview**, **Cancel**. Preview rebuilds the body's preview item from your typed values without saving so you can iterate. Apply commits + gives you a fresh test key in your inventory. Existing keys in player inventories continue to work after edits — the PDC tag is stable, only the visible appearance changes.

## Resetting cooldowns

```
/tcpvc reset <crate> player <name>
/tcpvc reset <crate> all
/tcpvc reset <crate> group <permission>
```

Force-reset cooldowns on every registered vault of the crate, for one player, everyone, or every player (online + offline via LuckPerms) holding a permission node. Useful for events, testing, or rolling back a problematic open.

`all` mode also wipes server-wide locks. The `group` variant requires LuckPerms for offline-player resolution; without it the scope narrows to currently-online players with a chat notice.

## Drop keys from spawner mobs (Wild Spawners integration)

If you have **Wild Spawners** installed alongside, you can configure crate keys to drop when mobs spawned by your wild presets die. See [WildSpawners integration →](/plugins/vault-crates/wildspawners-integration.md) for the full setup.

## Drop keys from vanilla mob deaths

You don't need WildSpawners for this — any plugin that runs a console command on mob death works. For example, with **EssentialsX**'s `/jail` plugin chain (or any custom event listener):

```yaml
# your custom event listener config
on-mob-death:
  enderman:
    chance: 0.05
    command: "tcpvc key give {killer} common normal 1"
```

Drop chance plugins, mythic-mobs drops, even datapacks that emit commands — anything that can run `tcpvc key give` works.

## Drop keys from quest completion

Quest plugins (Quests, BeautyQuests, BetonQuest, etc.) all support console commands as rewards. Same pattern:

```
console: tcpvc key give {player} legendary ominous 1
```

## Keys and OPs

OPs do **not** automatically have `tcpvc.use`. The permission defaults to `true` for everyone, so you don't need to grant it explicitly — but if you've explicitly negated it (e.g. `tcpvc.use: false` in a LuckPerms group), even OPs are blocked from opening crates until the permission is restored.

## Keys and the bypass permission

`tcpvc.bypass.droplock` (default: OP) lets a player pick up *any* vault drop regardless of the owner-lock. Useful for staff accounts that need to clean up dropped items, or for testing. Don't grant it to general players.

## Stacking keys

Crate keys are normal ItemStacks — they stack up to 64 per slot, respecting Minecraft's max stack size. Two keys of the same crate

* tier always stack; keys of different tiers (or different crates) don't.

The `/tcpvc key give-all` command issues one stack per player; if the player already has matching keys in their inventory, the new ones merge in.

## Renaming a crate

If you rename a crate (`common` → `commoner`) **after** keys are already in players' inventories, those old keys won't open new vaults — their `tcpvc:crate_id` PDC tag still says `common` and there are no `common` vaults left.

Rule of thumb: **don't rename crate ids in production.** It's a breaking change for every key already issued. If you really need to, issue replacement keys to affected players via `give-all`.

***

Next: [**The admin GUI →**](/plugins/vault-crates/admin-gui.md) · [**Commands & permissions →**](/plugins/vault-crates/commands-and-permissions.md)