BetterChat

For Paper / Purpur 1.21.x — Java 21 — Version 1.0.0

BetterChat rewrites your server's chat, join, quit and first-join messages using MiniMessage formatting. It ships with built-in placeholders, optional PlaceholderAPI and ServerRoles integration, and a mention highlight system — all driven from a single, well-commented config.yml.

The message pipeline is designed to be safe by default: player-typed messages are escaped and inserted last, so a normal player cannot inject colors, formatting tags, or placeholders into chat.

Features

• MiniMessage chat formatting — full gradient, color, decoration and reset support in your configured format string.
• Join / quit / first-join messages — each independently toggleable and fully formatted.
• Built-in placeholders — {player}, {displayname}, {world}, {online}, {message}.
• Optional PlaceholderAPI support — use any %placeholder% in your format strings when PlaceholderAPI is installed (for example %serverroles_prefix_formatted%).
• Optional ServerRoles integration — role prefixes and colors via PlaceholderAPI.
• Mention highlighting — @name highlights the mentioned player with a configurable color and sound.
• Safe message handling — player message content never passes through PlaceholderAPI, and is escaped unless the player has the formatting permission.
• Permission-gated formatting — only players with betterchat.format may use MiniMessage tags in their own messages.
• Bilingual language files — en_US and pt_PT included.
• In-game format debugging — inspect the placeholder resolution pipeline step by step.

Commands

Command	Description	Permission
/betterchat	Show command usage.	(none)
/betterchat reload	Reload config and language files, re-detect PlaceholderAPI.	betterchat.admin
/betterchat debugpapi [player]	Print the placeholder resolution pipeline for a player.	betterchat.admin
/betterchat debugformat [player]	Print the resolved chat/join/quit formats for a player.	betterchat.admin

Alias: /bchat.

Permissions

Node	Description	Default
betterchat.admin	Access to /betterchat admin subcommands (reload, debugpapi, debugformat).	op
betterchat.format	Allows using MiniMessage formatting tags in the player's own chat messages.	false

Note on betterchat.format: granting this node lets a player use MiniMessage tags in their messages. Only grant it to trusted players. Players without it have their tags escaped automatically, so their message content is always shown literally.

Configuration

The default config.yml:

language: en_US

features:
  chat-format: true
  join-quit-messages: true
  first-join-message: true
  # If true, players with betterchat.format can use MiniMessage tags in their messages.
  allow-message-minimessage-with-permission: true
  mention-highlight:
    enabled: true
    sound: "entity.experience_orb.pickup"
    format: "<yellow>@{mentioned}</yellow>"

formats:
  # Supports both built-in {placeholders} and PlaceholderAPI %placeholders%.
  chat: "%serverroles_prefix_formatted% %serverroles_color%{player}<reset>: <white>{message}</white>"
  join: "<green>+ <gray>{player}</gray></green>"
  quit: "<red>- <gray>{player}</gray></red>"
  first-join: "<gold>* <gray>{player}</gray> <yellow>joined for the first time!</yellow></gold>"

debug:
  papi: false
  placeholder-flow: false

Key points:

• Placeholders — built-in {...} placeholders are resolved first, then PlaceholderAPI %...%, and finally {message} is inserted (chat only). Message content never passes through PlaceholderAPI, which prevents placeholder injection from chat.
• formats.chat — the default format uses ServerRoles placeholders via PlaceholderAPI. If you do not run PlaceholderAPI, replace it with a plain format such as "<gray>{player}</gray>: <white>{message}</white>".
• mention-highlight — set sound: "" to disable the mention sound.
• debug — leave both off in normal operation; placeholder-flow is very verbose.

Installation

1. Requires Paper or Purpur 1.21+ and Java 21.
2. (Optional but recommended) install PlaceholderAPI if your format strings use %...% placeholders or ServerRoles integration.
3. Drop BetterChat.jar into your server's plugins/ folder.
4. Start the server once to generate config.yml and the language files.
5. Edit config.yml to taste and run /betterchat reload.

Dependencies

• PlaceholderAPI (optional) — required only if you use %...% placeholders in your formats, including the default ServerRoles-based chat format. Without it, built-in {...} placeholders and MiniMessage still work; any %...% tokens are left unresolved.
• ServerRoles (optional) — provides role prefix/color placeholders through PlaceholderAPI.

Support / Source

Source code: https://github.com/henriquescrrrr/carrageis-betterchat