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.