> 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/wild-spawners/vaultcrates-integration.md).

# Integration with Vault Crates

If you have **Vault Crates** 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

* Vault Crates installed.
* Wild Spawners installed (you've got this — that's why you're here).
* BetterTrialChambers 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/Wild Spawners/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 Vault Crates 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 →**](/plugins/wild-spawners/troubleshooting.md)