# config.yml

## `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

```yaml
license:
  marketplace: "voxel"
  key: "PASTE-YOUR-LICENSE-KEY-HERE"
```

#### `marketplace`

Which marketplace's verifier to use. Valid values:

* `voxel` — Voxel.shop. Recommended; the JAR you downloaded already has your key embedded.
* `selfhosted` (alias `esmp`) — esmp.fun. Same buyer experience as Voxel — the key is embedded in the JAR.
* `builtbybit` (alias `bbb` / `mcmarket`) — **stubbed in v1.0.** BBB isn't yet supported; the verifier always rejects with a pointer to the Voxel listing.

#### `key`

**Production buyers should not touch this field.** When you download the JAR from Voxel or esmp, your license key is automatically embedded inside it (`polymart.properties` resource, substituted at download time). The plugin reads that embedded key on startup.

The `license.key` field in `config.yml` is a **development fallback** for local builds where the JAR's embedded key is still the unsubstituted placeholder. Buyers see a warning in the console if the plugin falls back to the config key — that's the signal to re-download the JAR from the marketplace, because someone has been tinkering with it.

If you see this banner:

```
══════════════════════════════════════════════════
  License key sourced from config.yml fallback.
  This means polymart.properties still contains an
  un-substituted placeholder...
══════════════════════════════════════════════════
```

Re-download from the marketplace.

### 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). 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 →** · **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/installation/config.yml.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.