> For the complete documentation index, see [llms.txt](https://darkstarworks.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://darkstarworks.gitbook.io/plugins/mc/vc-documentation/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 | builtbybit — 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
* `builtbybit` — builtbybit.com

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/mc/vc-documentation/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.

***

## 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 `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/mc/vc-documentation/messages-yml.md) · [**Troubleshooting →**](/plugins/mc/vc-documentation/troubleshooting.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://darkstarworks.gitbook.io/plugins/mc/vc-documentation/config-yml.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.