# Managing Keys ## 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 [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 [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 player /tcpvc reset all /tcpvc reset group ``` 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 (TCP-WildSpawners integration) If you have **TCP-WildSpawners** installed alongside, you can configure crate keys to drop when mobs spawned by your wild presets die. See WildSpawners integration → 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 →** · **Commands & permissions →** --- # 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/your-first-crate/managing-keys.md?ask= ``` 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.