# Your First Crate

## Your first crate

This is a 5-minute walkthrough. By the end you'll have a working crate vault on your server that gives a player loot when they right-click it with the right key.

You'll use the example `common` crate that ships with the plugin — it's already configured with sensible defaults, so you don't have to edit `crates.yml` to test things out.

### Step 1 — Place a vault block

Hop into Creative or grab a Vault block however you usually do (`/give @s vault` works on most servers). Place it somewhere you won't lose track of — your spawn region or admin testing area is ideal.

A vanilla Vault block. Yes — that's the crate. No custom blocks, no resource pack, no fuss.

### Step 2 — Register it as a crate

Look directly at the vault block (within 8 blocks) and run:

```
/tcpvc set common
```

You should see a green confirmation message and a floating hologram appear above the vault showing:

```
Common Crate
Requires: Common Key or Ominous Common Key
7 prizes available
Per-player cooldown: 1d
```

The vault is now a registered crate. Its PDC has been tagged so the plugin knows it's not just a vanilla vault.

The example `common` crate ships with both `normal` and `ominous` tiers configured, so the hologram lists both keys. Either one works on the same vault block — the plugin selects which loot pool to roll based on the **held key's PDC tier**, not on whether the vault is in vanilla's "ominous state". (If you want a crate that only accepts one key, configure only that tier — `/tcpvc set` will force the vault's ominous flag to match.)

### Step 3 — Give yourself a key

The example `common` crate uses **Amethyst Shards** as its normal-tier key. Mint one with:

```
/tcpvc key give YourName common normal 1
```

Replace `YourName` with your in-game name. The amethyst shard you receive will have a `<gray>Common Key</gray>` display name and a custom lore line — that's how the plugin recognises it as a key rather than a regular amethyst shard.

(Pick up an amethyst shard from your inventory and look at it. The display name and lore mark it as the key. PDC tags do the actual matching.)

### Step 4 — Open the vault

Hold the key in your main hand and **right-click** the vault.

You should see:

* The vault closes/dims (vanilla "deactivated" state — that's the visual feedback that it accepted your open).
* The vault open sound plays.
* A small particle puff above the vault.
* Your inventory gains the rolled loot.
* A chat summary listing what you got.

Try right-clicking the vault again. The plugin tells you you've already opened it — and you can confirm by checking the hologram, which now shows "Last opened by: YourName".

### Step 5 — Test the cooldown reset

The example `common` crate uses a 24-hour per-player cooldown. To test the reset without waiting, you can either:

* Edit `crates.yml` and lower `reset-interval-seconds` to something small like `10`. Run `/tcpvc reload`. Wait 10 seconds. Right-click again — should work.
* Or use `/tcpvc gui`, click the `common` crate, click the **clock** button to open the cooldown Dialog, drag the slider down to 60 seconds. Auto-saves on Apply.
* Or force a one-off reset for yourself without changing the cooldown: `/tcpvc reset common player <yourname>`.

### Step 6 — Try the preview GUI

Left-click the vault (no key needed). A read-only chest opens showing every prize the crate can drop, with a percentage chance next to each. Players can use this to plan what they're saving for.

### Step 7 — Bulk open

Give yourself five keys:

```
/tcpvc key give YourName common normal 5
```

Wait for the cooldown (or force-reset as above). Now **shift + right-click** the vault. All five keys get consumed at once, the loot is aggregated into one chat summary, no per-key animation. Fast.

***

That's a complete crate cycle: place, register, key, open, preview, bulk. Everything else in the docs is configuration depth on top of this skeleton.

### Where to go next

* **Configuring crates.yml →** — define your own crates, configure loot pools, change the key items.
* **The admin GUI →** — every screen and what it does.
* **Managing keys →** — integrate with your shop plugin so players can buy keys.

### Cleaning up

If you're done testing and want to delete the example vault:

1. Sneak (hold shift) and break the vault block as an op. The plugin detects the admin sneak-break, removes its registration cleanly, destroys the hologram, and lets the break proceed.

Or:

1. Look at the vault and run `/tcpvc unset`.
2. Now break the block normally.

Don't try to break a registered vault without sneaking — the protection system blocks it on purpose. (A friendly chat hint will tell you so.)


---

# 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.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.