ChatModifier

NOTE: I generated ONLY this description with AI and I'm open for your ideas!

💬 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

🔐 Permissions

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

Shout cooldown reference

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