💬 ChatModifier

Chat plugin for a school Minecraft server (PaperMC 1.20.x / 1.21.x)

ChatModifier overhauls chat and player communication — it scopes messages to a configurable radius, handles private messages, a staff-only global broadcast, and an admin spy mode. It optionally integrates with LuckPerms to display rank prefixes.

✨ Features

📡 Local chat with range

• Messages are only visible to players within a configured radius
• Setting 0 = infinite range (entire world)
• Configurable cooldown between messages
• Ignores spectator-mode and vanished players

🔊 Shout (/shout, /s, /krzyk)

• Broadcasts a message to every player on the server
• Long cooldown configurable in config.yml
• Available to all players (no permission required)

📢 Global (/global, /g)

• Staff broadcast visible to everyone
• Requires the chatmodifier.command.global permission
• Can be disabled in config.yml

💌 Private messages (/msg, /reply)

• Send a private message to a specific player
• /reply (or /r) replies to the last conversation partner
• Handles vanished / spectator players correctly
• Tab-complete filters hidden players based on permission

🕵️ Chat spy (/spy)

• Separate toggles for chat spy and private-message spy
• Intercepted messages are prefixed with [SPY]
• Requires the chatmodifier.spy permission

🔤 Message filter

• Blocks disallowed characters (configurable regex)
• Banned word list in config.yml
• LuckPerms integration: rank prefixes shown in chat

📥 Installation

1. Download the .jar from GitHub
2. Place it in your server's plugins/ folder
3. Start the server — config files are generated automatically
4. Edit plugins/ChatModifier/config.yml and lang.yml
5. Reload with /reload confirm or restart the server

Requirements:

• PaperMC 1.20.x or 1.21.x
• Java 21+
• LuckPerms (optional — for rank prefix display)

🎮 Commands

| Command | Aliases | Description | Permission |
|---------|---------|-------------|------------|
| /shout <message> | /s, /krzyk | Broadcast to the whole server (cooldown applies) | (none — everyone) |
| /global <message> | /g | Staff broadcast | chatmodifier.command.global |
| /msg <player> <message> | /tell, /w, /message | Private message | (none — everyone) |
| /reply <message> | /r | Reply to last private message | (none — everyone) |
| /spy | — | Show spy status | chatmodifier.spy |
| /spy chat | — | Toggle chat spy | chatmodifier.spy |
| /spy msg | — | Toggle private-message spy | chatmodifier.spy |

🔐 Permissions

| Permission | Default | Description |
|------------|---------|-------------|
| chatmodifier.command.global | false | Access to /global |
| chatmodifier.cooldown.bypass | false | Skip chat cooldown |
| chatmodifier.spy | op | Access to /spy |
| chatmodifier.seehidden | false | See hidden/vanished players in /msg tab-complete |

LuckPerms example

/lp group admin permission set chatmodifier.command.global true
/lp group admin permission set chatmodifier.spy true
/lp group vip permission set chatmodifier.cooldown.bypass true

⚙️ Configuration

config.yml

# ------- [ CHAT ] ------- #
chat:
  distance: 32    # Message radius in blocks (0 = infinite)
  cooldown: 1500  # Time between messages in milliseconds

# ------- [ BANNED WORDS ] ------- #
banned-words: []
# Example: ["badword", "spam"]

# ------- [ GLOBAL ] ------- #
global:
  enabled: true

# ------- [ SHOUT ] ------- #
shout:
  enabled: true
  cooldown: 150000  # Cooldown in milliseconds (default 2.5 minutes)

# ------- [ COMMANDS ] ------- #
# Extra aliases registered at startup (beyond the built-in ones).
# Restart the server after changing these values.
# Built-in:  shout=[krzyk, s]  global=[g]  msg=[tell, w, message]  reply=[r]
commands:
  shout:
    extra-aliases: []
  global:
    extra-aliases: []
  msg:
    extra-aliases: []
  reply:
    extra-aliases: []
  spy:
    extra-aliases: []

Chat radius reference

| distance value | Effect |
|------------------|--------|
| 0 | Infinite (entire world) |
| 32 | Visible within 32 blocks |
| 64 | Visible within 64 blocks |

Shout cooldown reference

| shout.cooldown value | Duration |
|------------------------|----------|
| 60000 | 1 minute |
| 150000 | 2.5 minutes |
| 300000 | 5 minutes |
| 900000 | 15 minutes |

lang.yml

All player-facing messages live in plugins/ChatModifier/lang.yml. Edit any value to customise the text. Color codes use & (e.g. &c = red, &a = green, &7 = gray). Placeholders are documented inside the file.

chat:
  no-recipients: "&c[CM] Nobody heard you - No players within {distance} blocks!"
shout:
  cooldown: "&c[CM] You must wait {minutes}min. {seconds}s. before using this command again."

Adding custom command aliases

To add a custom alias (e.g. /bc as an alias for /shout), edit config.yml and restart:

commands:
  shout:
    extra-aliases: [ bc, broadcast ]

🌐 LuckPerms integration

When LuckPerms is installed, the plugin automatically fetches each player's prefix and prepends it to chat messages:

[Admin] Dominik: Hello!

Without LuckPerms only the player name is shown:

Dominik: Hello!

🔁 Version history

1.0.0

• Initial release
• Local chat with radius and cooldown
• Commands: /shout, /global, /msg, /reply, /spy
• Configurable extra aliases per command in config.yml
• LuckPerms integration
• Support for Minecraft 1.20.x and 1.21.x

🐛 Troubleshooting

Plugin won't load

1. Check the server version — Paper 1.20.x or 1.21.x is required (/version)
2. Check that you are running Java 21+ (java -version)
3. Look for [ChatModifier] errors in the server console

/global says no permission

Make sure the player / group has chatmodifier.command.global.

Chat does nothing at distance 0

Set chat.distance: 0 — the value 0 means infinite range.

Custom alias doesn't work

Make sure you restarted the server (not just /reload). Extra aliases are registered via CommandMap at startup.

LuckPerms prefix is not shown

Ensure LuckPerms is installed and loaded before ChatModifier.

🔁 Version History

Future Roadmap

• [ ] More customization
• [ ] Getting black list from API
• [ ] Custom nick system
• [ ] Database integration

0.1.0

• Initial release with core functionality.

🔗 Links

• GitHub: https://github.com/Dominos111G/ChatModifier
• Modrinth: https://modrinth.com/plugin/chatmodifier
• Issues: https://github.com/Dominos111G/ChatModifier/issues

📝 License

MIT License — Free to modify and distribute