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.notify permission
• 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.enabled is false in config.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.