> 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/config-yml.md).

# config.yml reference

`config.yml` controls **global** plugin behaviour. Per-crate behaviour lives in `crates.yml`; per-message text lives in `messages.yml`. This file is for the toggles that apply across every crate.

Defaults work for most servers — most admins never edit this file.

## License section

There's nothing to configure here — **your licence is embedded in the JAR you downloaded.** No key to paste, no activation step; the plugin reads the embedded licence automatically on startup.

```yaml
license:
  marketplace: "voxel"   # esmp | voxel — auto-managed
```

### `marketplace`

Which store the copy came from, used only for licence verification. Set automatically at download time — you normally never touch it.

* `esmp` — esmp.fun (set automatically on esmp.fun downloads)
* `voxel` — voxel.shop

If a download ever fails to verify, re-download the JAR from your purchase page (esmp.fun, or whichever store you bought it from) — the fresh copy re-embeds your licence.

## Crates section

```yaml
crates:
  bulk-open:
    enabled: true
    max-keys: 10
  drop-on-full-inventory:
    enabled: true
    owner-grace-seconds: 30
```

### `bulk-open.enabled`

When **true** (default), shift-right-clicking a registered vault consumes up to `max-keys` keys at once and aggregates the result into a single delivery + chat summary. Skips the per-key animation — fast and satisfying for bulk openers.

When **false**, shift-right-click behaves like a regular right-click (one key, full animation, single chat line). Set to false if you want every open to feel like a "moment" — e.g. on roleplay servers.

### `bulk-open.max-keys`

Max keys consumed in one bulk-open click. 1..64 (clamped). Default **10**. Players with more than this many keys can still bulk-open; they just have to click multiple times to consume them all.

### `drop-on-full-inventory.enabled`

When **true** (default), inventory-full overflow drops at the player's feet, marked owner-only for the grace window.

When **false**, overflow is dropped without an owner mark — anyone can pick it up. Disable this only on PvP/anarchy servers where you want loot-stealing as a feature.

### `drop-on-full-inventory.owner-grace-seconds`

How long the owner-only restriction applies after a drop. Default **30** seconds.

* `0` — owner-locked **until the item despawns naturally** (5 minutes vanilla). Useful if you want strong protection but accept the risk of items lingering forever if the opener logs off.
* Any positive number — locked for that many seconds, then anyone can pick up. Recommended.

Players with `tcpvc.bypass.droplock` (default OP) can pick up regardless.

## Holograms section

```yaml
holograms:
  enabled: true
  update-interval-seconds: 1
  y-offset: 1.5
  lines:
    title: true
    key-required: true
    prizes-count: true
    last-opener: false
    cooldown: true
```

### `holograms.enabled`

Master toggle. When **false**, no holograms appear. Useful for servers with strict entity counts or for screenshot/cinematic modes.

### `holograms.update-interval-seconds`

**Don't change this.** The reconcile loop runs every 1 second and the cooldown countdown depends on it. The setting exists for future flexibility but isn't currently honoured by the manager (the reconcile interval is hard-coded to 20 ticks).

### `holograms.y-offset`

How far above the vault block the floating text floats. Default **1.5** (half a block above the top face of the vault). Try **1.2** for tighter, **2.0** for higher.

### `holograms.lines.*`

Per-line global visibility. Each line can be turned off server-wide:

| Key            | Shows                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `title`        | The crate's display name                                                                           |
| `key-required` | Which key opens this crate                                                                         |
| `prizes-count` | How many distinct prizes are in the visible tier's pool                                            |
| `last-opener`  | Who most recently opened this vault (default off)                                                  |
| `cooldown`     | Live countdown for server-wide reset, static interval for per-player, "One-time only" for one-time |

Per-crate `hologram-overrides:` in `crates.yml` takes precedence — useful when one specific crate wants `last-opener` shown while the rest don't.

## Protection section

```yaml
protection:
  block-break: true
  explosion-protection: true
  piston-protection: true
```

### `protection.block-break`

When **true** (default), registered vaults can't be broken by anyone except admins doing a deliberate sneak-break (see the [admin GUI docs](/plugins/vault-crates/admin-gui.md)). Non-admins get a chat hint pointing at `/tcpvc unset`.

When **false**, anyone with vanilla block-break permission can break your registered vaults. Disable only on servers with their own rigorous claim/protection system.

### `protection.explosion-protection`

When **true** (default), registered vaults are filtered out of the explosion's block list before vanilla processing. Adjacent blocks still go boom — only the vault is preserved.

Covers: creeper explosions, TNT, fireballs, wind charges (entity explosions); plus beds in the Nether, respawn anchors in the Overworld (block explosions).

### `protection.piston-protection`

When **true** (default), pistons can't push or pull registered vaults. Vanilla vault hardness is 50, so this is normally a no-op — but it's defence-in-depth against datapack tweaks that lower vault hardness, or modded servers.

***

## Updates section

*(Added in 1.1.0.)* Vault Crates can check esmp.fun for new versions and, if you let it, download and install them for you.

```yaml
update:
  mode: notify
  check-interval-hours: 6
```

**This only applies to esmp.fun licences.** The update check authenticates with your licence key against esmp.fun's update API, and a download is **your own watermarked build** — checksum-verified, the current jar backed up, and the new one staged into the server's update folder to install on the next restart. Voxel copies skip update checks entirely; download new versions from your marketplace as usual. Servers on MC 26.x automatically receive the `-mc26` build.

### `mode`

How far the updater goes on its own. Each mode includes the ones above it:

* `off` — no update checks at all.
* `check-only` — check silently; results only via `/tcpvc update status`.
* `notify` (default) — also announce available updates in the console and to admins (holders of `tcpvc.admin`).
* `download` — also allow `/tcpvc update download` to fetch, verify and stage an update for the next restart.
* `auto-stage` — download, verify and stage new versions automatically.

In `notify` nothing is ever written to disk — you stay in control of when anything downloads.

### `check-interval-hours`

Hours between automatic checks. Minimum `1`, default `6`.

See [**Commands**](/plugins/vault-crates/commands-and-permissions.md) for the `/tcpvc update` subcommands (`check`, `download`, `restore`, `ignore`, `status`).

## Reloading

Most settings in this file take effect immediately on `/tcpvc reload`. Exceptions:

* **License section** — license verification only happens at startup. Changing `marketplace` requires a server restart.
* **Holograms `update-interval-seconds`** — the refresh task is scheduled once at startup; changing the cadence requires a server restart.
* **Holograms `enabled`** — toggling this at runtime works (next reconcile tick removes or spawns holograms), but the entity spawn-radius for clients won't refresh until they leave and re-enter the area.

***

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