# WildSpawners Compatibility

## Integration with TCP-WildSpawners

If you have **TCP-WildSpawners** 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-WildSpawners installed.
* TCP-VaultCrates 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 (the `wild-spawner` loot entry type just no-ops in `crates.yml`).

### 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 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 TCP-VaultCrates 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 →**


---

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