PaperChatLimiter
A powerful, fully configurable chat rate-limiting and auto-mute plugin for Paper 1.20 ~ 1.21.x servers.
PaperChatLimiter is designed to give server administrators complete control over player chat behavior. With a sophisticated Violation Level (VL) system, configurable cooldowns, smart spam detection, and automatic punishment escalation — all fully customizable through a single config.yml file.
Features
🚦 Chat Cooldown
- Set minimum intervals between messages (per-message and per-duplicate-content)
- Players are shown remaining cooldown time
- Separate cooldown for repeating identical messages
🛡️ Smart Spam Detection
- Detects repeated identical messages within a configurable time window
- Case-insensitive comparison, trim, and special character filtering options
- Configurable threshold before triggering actions
⚡ VL (Violation Level) System
- Each spam violation increases a player's VL score
- VL decays automatically over time
- Threshold-based actions — configure different actions at different VL levels:
- Warning messages
- Temporary or permanent mute
- Kick from server
- Execute custom console commands (LiteBans, ban plugins, etc.)
- Full placeholder support:
{player},{uuid},{vl},{total},{duration},{duration-seconds}
🔇 Auto-Mute with Escalation
- Progressive punishment: mute durations increase with repeat offenses
- Configurable escalation factor (e.g., 2×, 3× longer each time)
- Warn-before-mute mode with configurable warning count
- Offline mute persistence (players remain muted across sessions)
- Custom mute command support for integration with punishment plugins like LiteBans
🎯 Permission Bypass System
- Disable bypass by default — even OP players are restricted!
- Optionally enable permission-based bypass for trusted staff
- Three separate permission nodes: cooldown, spam detection, and mute immunity
👮 Admin Notifications
- Real-time notifications for staff with the
chatlimiter.notifypermission - Console logging of all violations
🌐 Internationalization
- Built-in English (
en_us) and Chinese (zh_cn) language files - Easy to edit or extend with custom language files
- Messages can also be overridden directly in
config.yml
Commands
| Command | Description | Permission |
|---|---|---|
/paperchatlimiter reload |
Reload plugin configuration | chatlimiter.reload |
/paperchatlimiter vl <player> |
View a player's violation level | chatlimiter.reload |
/paperchatlimiter unmute <player> |
Unmute a player | chatlimiter.reload |
/paperchatlimiter reset <player> |
Reset a player's VL and mute status | chatlimiter.reload |
Aliases: /chatlimiter, /pcl, /cl, /chlimit
Permissions
| Permission | Description | Default |
|---|---|---|
chatlimiter.bypass.cooldown |
Bypass message cooldown | OP |
chatlimiter.bypass.spam |
Bypass spam detection | OP |
chatlimiter.bypass.mute |
Immune to mute (can speak while muted) | false |
chatlimiter.notify |
Receive violation notifications | OP |
chatlimiter.reload |
Reload plugin configuration | OP |
Note: When
bypass.enabledisfalseinconfig.yml(the default), no one — including OPs — can bypass any restriction. Toggle it on to use the permission system above.
Configuration
Everything is configured in plugins/PaperChatLimiter/config.yml. Key sections:
- Cooldown — message interval timing
- Spam — duplicate message detection rules
- VL — violation level thresholds, decay rates, and action tiers
- Mute — duration, escalation, custom commands
- Bypass — permission override settings
- Notification — admin alerts and console logging
Duration strings support: 30s, 5m, 1h, 2d, 1w, permanent, or plain seconds.
Requirements
- Server: Paper 1.20 ~ 1.21.x (or compatible forks)
- Java: 17 or higher
Support
- Found a bug? Have a feature request? Open an issue on GitHub.
- Pull requests are welcome!
PaperChatLimiter — Keeping your server chat clean and fair.
