# VaultCrates Compatibility

## Integration with TCP-VaultCrates

If you have **TCP-VaultCrates** installed alongside this plugin, you can configure spawner mobs to drop crate keys when they die. The two plugins were built to work together — this is the cleanest way to give players reliable, configurable key drops without writing your own listener.

### What you need

* TCP-VaultCrates installed.
* TCP-WildSpawners installed (you've got this — that's why you're here).
* TrialChamberPro v1.4.0+ (the free dependency for both).

That's it. The integration is **soft-depend** in both directions: WildSpawners runs fine without VaultCrates (key-drops just no-op), and VaultCrates runs fine without WildSpawners (its own `wild-spawner` loot entry type just no-ops).

### Configure key drops on a wild preset

Open `plugins/TCP-WildSpawners/wild-presets.yml`. Find the preset you want to drop keys (or create a new one). Add a `key-drops:` section:

```yaml
presets:
  dungeon_guardian:
    display-name: "<dark_red>Dungeon Guardian</dark_red>"
    provider: mythicmobs
    normal-mobs:
      - DungeonGuardian
    ominous-mobs:
      - EliteDungeonGuardian
    enabled: true

    key-drops:
      - { crate: "common",    tier: "normal",  chance: 0.25 }
      - { crate: "legendary", tier: "ominous", chance: 0.02 }
```

| Field    | Meaning                                     |
| -------- | ------------------------------------------- |
| `crate`  | Crate id from your VaultCrates `crates.yml` |
| `tier`   | `normal` or `ominous`                       |
| `chance` | Probability per kill, 0.0..1.0              |

Each entry rolls **independently**, so a single mob can drop both a common key (25%) and a legendary key (2%). Or neither.

Apply: `/tcpws reload`. Mobs from that preset now have a chance to drop keys when they die.

### How it works under the hood

So you know what to expect:

1. WildSpawners' tether scan loop tags every mob spawned by a wild preset with a PDC entry indicating which preset spawned it. The tag is rewritten on every scan pass and survives until the mob is removed from the world.
2. When a tagged mob dies, WildSpawners' `KeyDropListener` reads the PDC tag, finds the matching preset, and looks up its `key-drops` list.
3. For each drop entry, it rolls the chance and on success calls VaultCrates' `KeyDropService` (registered via Bukkit's `ServicesManager`) to mint and drop the key at the mob's location.
4. The dropped key is a regular ItemStack with VaultCrates' PDC tags — picking it up gives you a working crate key, identical to what `/tcpvc key give` would issue.

### Tips

* **Test with high chances first.** Set `chance: 1.0` while testing so every kill drops a key. Once you've verified the integration, lower it to your real values.
* **Keys land at the mob's death location.** Players who kill the mob from range still need to reach the body to pick up the key. Same as vanilla mob drops.
* **Tagged mobs persist.** A mob that despawns while loaded carries its preset tag with it.
* **VaultCrates not loaded?** Server starts fine. The first key-drop attempt logs a one-time INFO line ("Preset X configures key-drops but TCP-VaultCrates isn't installed — drops disabled.") and every subsequent kill silently no-ops.

### A reverse loop: VaultCrates dropping spawners

The other direction works too. In VaultCrates' `crates.yml`, you can configure a `wild-spawner` loot entry type that gives a player a wild-preset spawner item:

```yaml
ominous:
  loot:
    rolls: 3
    entries:
      - { type: wild-spawner, preset-id: dungeon_guardian, weight: 2, announce: true }
```

The player who opens this crate has a chance to receive a deployable `dungeon_guardian` spawner block. They can place it anywhere on the map.

The full ecosystem closes the loop:

```
spawner mobs drop keys → keys open vaults → vaults can reward more spawners
```

If WildSpawners isn't loaded, the `wild-spawner` entry logs a one-time warning at give-time and is skipped. Same soft-depend story.

### Worked example: a complete progression loop

You set up:

* **A `goblin_camp` preset** with `key-drops: [{ crate: common, tier: normal, chance: 0.25 }]`.
* **A `common` crate** in VaultCrates whose normal-tier loot pool has weight-1 entries for cobblestone/iron/diamond, plus a weight-2 `wild-spawner` entry for `goblin_camp` (so opening the crate has a chance to drop another spawner).

A player buys their first `goblin_camp` spawner from your shop for $5. They deploy it.

1. They fight the goblins. 25% of kills drop a Common Key.
2. They accumulate keys. They walk to a Common Vault somewhere else on your map (which you configured earlier — see VaultCrates docs).
3. They open the vault. Sometimes they get cobblestone. Sometimes iron. Occasionally — by the weight-2 wild-spawner entry — they get **another `goblin_camp` spawner**.
4. They place the new spawner somewhere else and start the loop again.

Three plugins, one progression curve. No external integrations, no scripting, no extra dependencies.

***

Next: **Troubleshooting →**


---

# 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-wildspawners/vaultcrates-compatibility.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.