💬 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