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.