> ## Documentation Index
> Fetch the complete documentation index at: https://perplayerkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Customize Plugin Messages and Broadcasts

> Configure the messages PerPlayerKit broadcasts when players load kits, repair gear, or perform other actions. Uses MiniMessage formatting for full color support.

Every player-facing string in PerPlayerKit — from the join MOTD to the per-action broadcast that fires when someone loads a kit — uses [MiniMessage](https://docs.papermc.io/adventure/minimessage/) formatting. MiniMessage replaces legacy `§` color codes with readable XML-style tags, giving you precise control over colors, gradients, and text decorations without any external tools. Edit `config.yml` to change the wording, colors, and which audience sees each message.

***

## MiniMessage Quick Reference

MiniMessage tags wrap the text they affect and close with a matching slash tag. You can nest and combine them freely.

| Tag                                                  | Effect               | Example                                        |
| ---------------------------------------------------- | -------------------- | ---------------------------------------------- |
| `<red>` … `</red>`                                   | Named color          | `<red>Warning!</red>`                          |
| `<aqua>`, `<green>`, `<gray>`, `<gold>`, `<white>` … | Named colors         | `<gold>Gold text</gold>`                       |
| `<color:#RRGGBB>`                                    | Exact RGB color      | `<color:#FF6B35>Custom orange</color:#FF6B35>` |
| `<b>`                                                | Bold                 | `<b>Important</b>`                             |
| `<i>`                                                | Italic               | `<i>Hint</i>`                                  |
| `<u>`                                                | Underline            | `<u>/kit</u>`                                  |
| `<st>`                                               | Strikethrough        | `<st>Removed</st>`                             |
| `<reset>`                                            | Clear all formatting | `<reset>Plain text`                            |

**Combined example:**

```xml theme={null}
<gray>%player% <aqua><b>loaded</b></aqua> a kit</gray>
```

For the complete MiniMessage specification, visit the [PaperMC Adventure documentation](https://docs.papermc.io/adventure/minimessage/).

***

## Message of the Day (MOTD)

The MOTD displays a multi-line welcome message to players after they join. The `delay` field controls how many seconds the plugin waits before sending it, which prevents the message from being buried under server join noise.

```yaml config.yml theme={null}
motd:
  enabled: true
  delay: 5
  message:
    - ""
    - "<gray>   <st>                </st> <aqua><b>Per Player Kits</b></aqua><gray> <st>                </st>"
    - ""
    - "         <white>Type <aqua>/kit<white>, <aqua>/k <white>or <aqua>/pk<white> to get started!"
    - ""
```

| Field     | Type    | Description                                                                                                        |
| --------- | ------- | ------------------------------------------------------------------------------------------------------------------ |
| `enabled` | boolean | Set to `false` to completely disable the MOTD.                                                                     |
| `delay`   | integer | Seconds after joining before the message is delivered. `5` gives the player time to finish loading into the world. |
| `message` | list    | Each list entry is one chat line. Use `""` for blank spacer lines. All MiniMessage tags are supported.             |

***

## Scheduled Broadcast

The scheduled broadcast periodically sends a message to all online players. Use it to remind players about kit commands, announce events, or display server rules.

```yaml config.yml theme={null}
scheduled-broadcast:
  enabled: true
  period: 90
  messages:
    - "Example message"
```

| Field      | Type    | Description                                                                                         |
| ---------- | ------- | --------------------------------------------------------------------------------------------------- |
| `enabled`  | boolean | Set to `false` to stop all scheduled broadcasts.                                                    |
| `period`   | integer | Interval in **seconds** between broadcasts.                                                         |
| `messages` | list    | One or more message strings in MiniMessage format. All entries broadcast simultaneously each cycle. |

***

## Per-Action Messages

PerPlayerKit broadcasts a configurable message to the server each time a player performs a kit-related action. Every action has its own block so you can enable, word, and permission-gate each one independently.

```yaml config.yml theme={null}
messages:
  disable-kit-messages: false
  player-repaired:
    enabled: true
    message: "<gray>%player% repaired their gear</gray>"
    permission: "perplayerkit.kitnotify"
  player-healed:
    enabled: true
    message: "<gray>%player% healed themselves</gray>"
    permission: "perplayerkit.kitnotify"
  player-opened-kit-room:
    enabled: true
    message: "<gray>%player% opened the Kit Room</gray>"
    permission: "perplayerkit.kitnotify"
  player-loaded-private-kit:
    enabled: true
    message: "<gray>%player% loaded a kit</gray>"
    permission: "perplayerkit.kitnotify"
  player-loaded-public-kit:
    enabled: true
    message: "<gray>%player% loaded a public kit</gray>"
    permission: "perplayerkit.kitnotify"
  player-loaded-enderchest:
    enabled: true
    message: "<gray>%player% loaded an ender chest.</gray>"
    permission: "perplayerkit.kitnotify"
  player-copied-kit:
    enabled: true
    message: "<gray>%player% copied a kit</gray>"
    permission: "perplayerkit.kitnotify"
  player-copied-ec:
    enabled: true
    message: "<gray>%player% copied an ender chest</gray>"
    permission: "perplayerkit.kitnotify"
  player-regeared:
    enabled: true
    message: "<gray>%player% regeared</gray>"
    permission: "perplayerkit.kitnotify"
```

### Fields

<ParamField path="disable-kit-messages" type="boolean" default="false">
  **Global off switch.** Set to `true` to silence every action broadcast regardless of individual `enabled` values, the `broadcast-kit-messages` feature flag, or player permissions. Use this when you want zero chat noise from the plugin without editing each message block.
</ParamField>

<ParamField path="[action].enabled" type="boolean" default="true">
  Controls whether this specific message type is broadcast. Set to `false` to suppress only this action while leaving all others active.
</ParamField>

<ParamField path="[action].message" type="string">
  The broadcast text in MiniMessage format. The `%player%` placeholder is replaced with the acting player's name at runtime. If `use-display-name` is enabled in your server config, the player's display name is used instead.
</ParamField>

<ParamField path="[action].permission" type="string" default="perplayerkit.kitnotify">
  Only players who hold this permission will see the broadcast. The default node `perplayerkit.kitnotify` is granted to all players by default, so every online player sees messages unless you explicitly deny the node or change it to a restricted permission.
</ParamField>

### Available Action Keys

| Key                         | Fires when…                                     |
| --------------------------- | ----------------------------------------------- |
| `player-repaired`           | A player uses the repair command or GUI button. |
| `player-healed`             | A player uses the heal command.                 |
| `player-opened-kit-room`    | A player opens the Kit Room GUI.                |
| `player-loaded-private-kit` | A player loads one of their own personal kits.  |
| `player-loaded-public-kit`  | A player loads a public/shared kit.             |
| `player-loaded-enderchest`  | A player loads their saved enderchest.          |
| `player-copied-kit`         | A player copies another player's kit.           |
| `player-copied-ec`          | A player copies another player's enderchest.    |
| `player-regeared`           | A player uses `/regear` or `/rg`.               |

***

## Sounds

PerPlayerKit plays sounds to give players tactile feedback for GUI interactions and command results. All sound values must be valid [Bukkit Sound enum](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Sound.html) names.

```yaml config.yml theme={null}
sounds:
  enabled: true
  success: ENTITY_PLAYER_LEVELUP
  failure: ENTITY_ITEM_BREAK
  click: UI_BUTTON_CLICK
  open_gui: UI_BUTTON_CLICK
  close_gui: UI_BUTTON_CLICK
```

| Field       | Default                 | Description                                                                      |
| ----------- | ----------------------- | -------------------------------------------------------------------------------- |
| `enabled`   | `true`                  | Set to `false` to disable all plugin sounds globally.                            |
| `success`   | `ENTITY_PLAYER_LEVELUP` | Plays on successful actions such as saving or loading a kit.                     |
| `failure`   | `ENTITY_ITEM_BREAK`     | Plays when an action fails, such as trying to use a command in a disabled world. |
| `click`     | `UI_BUTTON_CLICK`       | Plays when a player clicks a button inside a GUI.                                |
| `open_gui`  | `UI_BUTTON_CLICK`       | Plays when a GUI screen opens.                                                   |
| `close_gui` | `UI_BUTTON_CLICK`       | Plays when a GUI screen closes.                                                  |