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

# PumpkinMsg Configuration Guide: Formats and Messages

> Edit plugins/PumpkinMsg/config.toml to customize message formats, placeholder tokens, and all UI strings using full MiniMessage support.

PumpkinMsg stores its entire configuration in a single file: `plugins/PumpkinMsg/config.toml`. The file is created automatically the first time you start the server or proxy. It contains two top-level sections — `[format]` controls how messages look, and `[messages]` controls every UI string the plugin sends to players. You do not need to restart the server to apply changes; run `/pumpkinreload` and the new values take effect immediately.

## Format Section

The `[format]` section defines the visual appearance of private messages for each audience: the sender, the recipient, and watching staff members. Every value is a MiniMessage string that supports hex colors, RGB gradients, and text decoration.

```toml theme={null}
[format]
# Sender's view: <target> = recipient name, <message> = the message text
sender = "<#ABB2BF>[<#FF9500>Me <#5C6370>-> <#61AFEF><target><#ABB2BF>] <white><message>"

# Recipient's view: <sender> = sender name, <message> = message text
receiver = "<#ABB2BF>[<#61AFEF><sender> <#5C6370>-> <#FF9500>Me<#ABB2BF>] <white><message>"

# Staff spy view: <sender>, <target>, <sender_prefix>, <target_prefix>, <message>
spy = "<#C678DD>[Spy] <sender_prefix><#61AFEF><sender> <#5C6370>-> <target_prefix><#61AFEF><target><#5C6370>: <#D19A66><message>"

# Command spy: <player>, <server>, <command>, <player_prefix>
cmdspy = "<#C678DD>[Cmd Spy] <player_prefix><#61AFEF><player> <#5C6370>used <white>/<command> <#5C6370>on <#E5C07B><server>"
```

### Format Placeholder Tokens

| Token             | Available in                | Description                                |
| ----------------- | --------------------------- | ------------------------------------------ |
| `<target>`        | `sender`                    | Username of the message recipient          |
| `<sender>`        | `receiver`, `spy`           | Username of the message sender             |
| `<message>`       | `sender`, `receiver`, `spy` | The message body (injection-safe)          |
| `<sender_prefix>` | `spy`                       | LuckPerms prefix of the sender             |
| `<target_prefix>` | `spy`                       | LuckPerms prefix of the target             |
| `<player>`        | `cmdspy`                    | Username of the player who ran the command |
| `<player_prefix>` | `cmdspy`                    | LuckPerms prefix of that player            |
| `<command>`       | `cmdspy`                    | The command string that was executed       |
| `<server>`        | `cmdspy`                    | The server the command was run on          |

<Note>
  The `<message>` token is injection-safe. Player-supplied text is passed to MiniMessage as a plain-text literal, so players cannot use color codes, gradients, or click events inside their messages, no matter what they type.
</Note>

<Tip>
  On Paper servers you can include any `%placeholder%` from PlaceholderAPI in your `sender` and `receiver` formats. For example, `%luckperms_prefix%` resolves to the viewing player's own prefix.
</Tip>

## Messages Section

The `[messages]` section controls every feedback string the plugin displays. All values are MiniMessage strings and support the same color and formatting features as the format section.

```toml theme={null}
[messages]
# Usage and Error Messages
usage              = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>Usage: /msg <player> <message>"
ignore-usage       = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>Correct usage: /ignore <player>"
reply-usage        = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>Usage: /reply <message>"
no-reply-target    = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>You have no one to reply to."
player-offline     = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>That player is offline or not on the network."
no-permission      = "<#E06C75>You do not have the required permissions for this."
reload-success     = "<#FF9500>PumpkinMsg <#5C6370>» <#98C379>Configuration reloaded successfully!"

# Restrictions
cannot-msg-self    = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>You cannot message yourself."
cannot-ignore-self = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>You cannot ignore yourself."
cannot-reply-self  = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>Reply error: Invalid target."

# Privacy and Blocking
sender-toggled-off  = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>Your private messages are disabled."
target-toggled-off  = "<#FF9500>PumpkinMsg <#5C6370>» <#D19A66>The recipient has their private messages turned off."
player-ignoring-you = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>You cannot contact this user."
ignored-player      = "<#FF9500>PumpkinMsg <#5C6370>» <#98C379>You are now ignoring <#61AFEF><target><#98C379>."
unignored-player    = "<#FF9500>PumpkinMsg <#5C6370>» <#E5C07B>You are no longer ignoring <#61AFEF><target><#E5C07B>."
toggle-on           = "<#FF9500>PumpkinMsg <#5C6370>» <#98C379>Private messages enabled."
toggle-off          = "<#FF9500>PumpkinMsg <#5C6370>» <#E06C75>Private messages disabled."

# Staff / SocialSpy
spy-enabled     = "<#C678DD>[Staff Spy] <#5C6370>» <#98C379>Global mode enabled."
spy-disabled    = "<#C678DD>[Staff Spy] <#5C6370>» <#E06C75>Global mode disabled."
spy-target-set  = "<#C678DD>[Staff Spy] <#5C6370>» <#61AFEF>Watching: <white><target>."
cmdspy-enabled  = "<#C678DD>[Cmd Spy] <#5C6370>» <#98C379>Command spy enabled <#E5C07B>(<mode>)."
cmdspy-disabled = "<#C678DD>[Cmd Spy] <#5C6370>» <#E06C75>Command spying disabled."
```

### Messages Placeholder Tokens

A subset of message strings support their own tokens:

| Token      | Used in                                                | Description                                    |
| ---------- | ------------------------------------------------------ | ---------------------------------------------- |
| `<target>` | `ignored-player`, `unignored-player`, `spy-target-set` | The player name being referenced               |
| `<mode>`   | `cmdspy-enabled`                                       | The active cmdspy mode (`global`, server name) |

## Applying Changes

After editing `config.toml`, run the reload command from the game or console — no server restart is required.

```bash theme={null}
/pumpkinreload
```

<Warning>
  TOML is whitespace-sensitive. Make sure every value remains on a single line and is wrapped in double quotes. Broken TOML syntax will prevent the plugin from loading the file and it will fall back to built-in defaults.
</Warning>