> 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/ws-documentation/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
  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 →**](/plugins/mc/ws-documentation/mining-and-redeploy.md) · [**messages.yml →**](/plugins/mc/ws-documentation/messages-yml.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/ws-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.