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

# 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

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

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

`marketplace` is 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).

## Holograms section

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

### `enabled`

Master toggle. When `false`, no holograms appear. Spawner position tracking, the mob tether, and re-place cooldowns keep working — this toggle is visual only. (The refresh task runs at a fixed 1 s cadence.)

### `y-offset`

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

### Per-line visibility

| Key        | Shows                                                                              |
| ---------- | ---------------------------------------------------------------------------------- |
| `title`    | The preset's display name                                                          |
| `owner`    | "Owner: " — only when the preset has `griefing-protection: true`                   |
| `state`    | "Spawning: " (cycling; obfuscated until a player is in range) 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
  require-silk-touch: false
  owner-only: false
  drop-on-non-player-break: 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.

### `require-silk-touch`

When `true`, mining a wild spawner requires a Silk Touch tool; attempts without one are rejected with a chat message. Default `false`.

### `drop-on-non-player-break`

When `true`, non-player destruction (TNT / creeper / other explosions) drops the state-preserving spawner item. When `false` (default), registered spawners are filtered out of explosions entirely — TNT looting is impossible.

(`/tcpws preview` always requires an air block at the crosshair — it never replaces existing blocks.)

## 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 — lower numbers run first (higher precedence). The default `1` overrides wandering but yields to attack-target goals, so mobs still chase players first and return after disengaging. Don't touch unless you know what you're doing.

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

## Updates section

*(Added in 1.1.0.)* Wild Spawners 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 and BuiltByBit 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 `/tcpws update status`.
* `notify` (default) — also announce available updates in the console and to admins (holders of `tcpws.admin`).
* `download` — also allow `/tcpws 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/wild-spawners/commands-and-permissions.md) for the `/tcpws update` subcommands (`check`, `download`, `restore`, `ignore`, `status`).

## Reloading

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

* **License section** — license verification only happens at startup. Changing `marketplace` requires a server restart.
* **`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 →**](/plugins/wild-spawners/mining-and-redeploy.md) · [**messages.yml →**](/plugins/wild-spawners/messages-yml.md)