> For the complete documentation index, see [llms.txt](https://eggsess-plugins.gitbook.io/eggsess-plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://eggsess-plugins.gitbook.io/eggsess-plugins/wandering-trader-announcer/configuration.md).

# Configuration

### **Introduction**

The Wandering Trader Announcer plugin provides four configuration files to control its behaviour, messages, and player-specific preferences:

* `config.yml` - Controls general plugin settings such as announcement behaviour, sound effects, and filters.
* `messages.yml` - Contains all plugin messages, supporting MiniMessage formatting by default.
* `players.yml` - Stores players who have opted out of Wandering Trader announcements.
* `gui.yml` - Holds information related to the GUI and its items.

***

### **`config.yml`**

This file defines the core settings for the Wandering Trader Announcer plugin.

#### **General Announcement Settings**

| Setting                        | Default | Description                                                                                                                                                              |
| ------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `announcement-per-world`       | `false` | If `true`, only players in the same world as the Wandering Trader will receive notifications. If `false`, all players on the server will receive the announcement.       |
| `only-announce-natural-spawns` | `false` | If `true`, only naturally spawned Wandering Traders will trigger notifications. If `false`, all trader spawns (including command or spawn egg spawns) will be announced. |

#### **Sound Effects**

| Setting                  | Default                              | Description                                                                                             |
| ------------------------ | ------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `spawn-event-play-sound` | `true`                               | If `true`, a sound will play for players who have notifications enabled when a Wandering Trader spawns. |
| `spawn-event-sound`      | `'minecraft:item.goat_horn.sound.0'` | Defines the sound played when a Wandering Trader spawns. Any valid Minecraft sound ID can be used.      |

***

### **`messages.yml`**

This file contains all configurable messages for the plugin, allowing full customization of announcements, errors, and command responses.

#### **Key Features**

* **Supports MiniMessage formatting** (default) and legacy colour codes (`&` / `§`).
* **MiniMessage and legacy codes cannot be mixed in a single message.**
* **Placeholders** allow for dynamic message content.

#### **Available Placeholders**

| Placeholder                              | Description                                                                   |
| ---------------------------------------- | ----------------------------------------------------------------------------- |
| `%prefix%`                               | Inserts the plugin’s message prefix.                                          |
| `%player%`                               | The player executing the command.                                             |
| `%target%`                               | The affected player (used in announcement commands and spawn event messages). |
| `%world%`                                | The world where the Wandering Trader spawned.                                 |
| `%trader_x%`, `%trader_y%`, `%trader_z%` | The Wandering Trader’s coordinates.                                           |
| `%path%`                                 | Config path with '-' removed for clarity. Used in GUI's.                      |
| `%sound%`                                | Config sound value. Used in GUI's.                                            |
| `%given_input%`                          | Player chat input, used in the GUIs to take in Player input through chat.     |

This file controls the format of messages displayed by the plugin, including:

* Announcements for trader spawns.
* Command responses (e.g., toggling notifications).
* Error messages (e.g., missing permissions or incorrect commands).

***

### **`players.yml`**

This file manages the list of players who have disabled Wandering Trader announcements.

#### **Key Features**

* Stores the **UUIDs** of players who have opted out.
* The plugin **automatically updates this file** when players toggle notifications.
* **⚠️ Warning:** **Do not edit this file manually while the server is running**, as it may be overwritten when the plugin updates dynamically.

#### **Example Format**

```yaml
toggled-off-list:
  - 'b1a2c3d4-e5f6-7890-abcd-ef1234567890'
  - '123e4567-e89b-12d3-a456-426614174000'
```

If a player's UUID is listed here, they will **not receive** Wandering Trader announcements.

***

### **`gui.yml`**

This file manages settings for the GUI's.

#### **Key Features**

* All GUI items and their names / lore are customizable.
* MiniMessage is supported for the title, and all item names and lore.
* Panel Items do not need names / lore as those items have hidden toolclips. 
* Place Holders can also be used here, %prefix% and %player% work in most cases, and there are specialized place holders including %path%, %sound%, and %given\_input% that in specific cases.