ChatLimiter

# 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.*