# config.yml

## `config.yml` reference

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

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

### License section

```yaml
license:
  marketplace: "voxel"
```

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.** Not yet supported.

Production buyers don't need to paste a license key anywhere — the JAR you downloaded from the marketplace already has it embedded. Just set `marketplace` to match where you bought it.

### Holograms section

```yaml
holograms:
  enabled: true
  y-offset: 1.8
  update-interval-seconds: 1
  lines:
    title: true
    owner: true
    state: true
    provider: false
```

#### `enabled`

Master toggle. When `false`, no holograms appear.

#### `y-offset`

How far above the spawner block the floating text floats. Default **1.8** (around half a block above the top face).

#### `update-interval-seconds`

How often the hologram refresh task runs (drives the cooldown countdown and the cycling-mob-name animation). Default `1`. Don't change unless you're profiling — anything above 2 makes the countdown feel choppy.

#### Per-line visibility

| Key        | Shows                                                            |
| ---------- | ---------------------------------------------------------------- |
| `title`    | The preset's display name                                        |
| `owner`    | "Owner: " — only when the preset has `griefing-protection: true` |
| `state`    | "Activating…" or "Cooldown: MM:SS"                               |
| `provider` | The provider name (vanilla / mythicmobs / etc.)                  |

Per-preset `hologram-overrides:` in `wild-presets.yml` takes precedence over these globals.

### Mining section

```yaml
mining:
  enabled: true
  hardness-seconds: 10.0
  owner-only: false
  preview-spawner-replaces-block: false
```

#### `enabled`

When `true` (default), wild spawners can be mined up by players holding the right tool. When `false`, mining is disabled entirely — spawners become permanent fixtures.

#### `hardness-seconds`

How long it takes to mine a wild spawner. Default `10.0` seconds — roughly the obsidian mining time. The plugin simulates the crack animation manually since vanilla doesn't have a fixed hardness for trial spawners.

Lower = faster mining. Higher = griefers can't strip your spawners without a long commitment.

#### `owner-only`

When `true`, only the player who placed a spawner can mine it (unless they have `tcpws.mine.bypass-owner`). Same effect as per-preset `griefing-protection: true`, but applied globally across every preset.

Default `false` — most servers want anyone to be able to mine and relocate spawners they've been issued.

#### `preview-spawner-replaces-block`

When `true`, `/tcpws preview` replaces the targeted block with a trial spawner block (and restores the original block after 30 seconds). When `false` (default), preview only works against air blocks — the player needs to look at empty space.

### Mob tether section

```yaml
mobs:
  tether-enabled: true
  tether-max-distance: 16.0
  tether-inner-radius-fraction: 0.5
  tether-speed: 1.0
  tether-priority: 1
  tether-scan-interval-ticks: 40
```

#### `tether-enabled`

When `true` (default), spawned mobs that wander too far from the spawner are pulled back by Paper's pathfinder.

#### `tether-max-distance`

Distance in blocks at which the tether engages. Default `16.0` — matches roughly the trial-spawner activation range.

#### `tether-inner-radius-fraction`

Hysteresis. The tether engages when the mob is `tether-max-distance` or further; the tether disengages when the mob is back within `tether-max-distance × tether-inner-radius-fraction` blocks. Default `0.5` — engages at 16+ blocks, disengages at 8 blocks. Prevents the mob from oscillating at the boundary.

#### `tether-speed`

Movement-speed multiplier applied during tethering. Default `1.0` (vanilla speed). Set higher (e.g. `1.5`) if your server has wide spawner setups and you want mobs to return faster.

#### `tether-priority`

Pathfinder-goal priority. Default `1` (highest). Lower values let other goals (target nearest player, etc.) take precedence. Don't touch unless you know what you're doing — the default works.

#### `tether-scan-interval-ticks`

How often the scan loop checks every spawner for tracked mobs. Default `40` ticks (every 2 seconds). Lower values are more responsive; higher values are cheaper.

The loop iterates only currently-loaded chunks, so the cost scales with active spawners, not total spawners.

### GUI section

```yaml
gui:
  add-mob-jump-to-new-page: false
```

#### `add-mob-jump-to-new-page`

When you add a mob via the GUI's mob-list editor, the new mob may land on a different page than the one you were viewing (if the list is long). When `true`, the GUI auto-navigates to the new mob's page. When `false` (default), it stays on the current page and sends a chat hint:

```
Added Goblin to page 3 of 5.
```

Either way works — pick whichever your admins prefer.

### Reloading

Most settings take effect on `/tcpws reload`. Exceptions:

* **License section** — license verification only happens at startup. Changing `marketplace` requires a server restart.
* **`holograms.update-interval-seconds`** — the timer is set up once at enable; restart to apply changes.
* **`mobs.tether-scan-interval-ticks`** — same; the timer task is scheduled at enable.

Most other toggles are read every event, so changes apply immediately on reload.

***

Next: **Mining and re-deploying →** · **messages.yml →**


---

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