> 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/wildspawners-integration.md).

# Integration with Wild Spawners

If you have **Wild Spawners** 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

* Wild Spawners installed.
* Vault Crates 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 (the `wild-spawner` loot entry type just no-ops in `crates.yml`).

## 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 at the bottom:

```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. Multiple entries in the same list just give you independent dice.

Apply: in WildSpawners, run `/tcpws reload` (or restart). Mobs from that preset now have a chance to drop keys when they die.

## How it works under the hood

Just 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' key-drop listener 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; if it gets pulled back into the world by some weird mechanic, the tag is still there. Practically: don't worry about edge cases.
* **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. No errors, no spam.

## A reverse loop: VaultCrates dropping spawners

The other direction works too. In `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.

***

Next: [**Troubleshooting →**](/plugins/vault-crates/troubleshooting.md)