Gavelry

Advanced chat filtering and case management for Minecraft servers.

 

 

---

About

Gavelry is a chat filter and case management plugin. Every flagged message opens a case with the surrounding chat context attached, so staff can review it, take action, and close it from an in-game GUI without touching the config or running extra commands.

There are four filter categories: slurs, profanity, advertising, and spam. Each one has its own action, severity level, and escalation rules. A first-time spammer gets a warning. A repeat slur offender gets a permanent mute. You decide what happens and when.

Config is at plugins/gavelry/config.yml.

---

Installation

Drop the Gavelry .jar into your plugins/ folder on any 1.21.1 build of PaperMC, Spigot, or Bukkit. No other plugins are required.

Optional integrations:

Plugin	What it does
LiteBans	Mutes go through LiteBans instead of the built-in system
EssentialsX	Mutes go through EssentialsX
LuckPerms	Lets you set trusted groups with relaxed filtering
Vault	Permission lookups via Vault

Gavelry falls back to its built-in mute system if the configured provider is not installed.

---

Filter System

Each chat message is checked against four categories. A category can be set to one of four actions:

Action	What happens
WARN_ONLY	Message goes through, player gets a private warning, case is opened
QUEUE_REVIEW	Message is blocked, case is queued for staff to review
AUTO_MUTE	Message is blocked, player is muted for the set duration
AUTO_KICK	Player is kicked immediately

Escalation is per-player within a 24-hour window. Set a threshold and Gavelry will switch to a harsher action after that many offenses.

---

Case System

Every filter hit creates a case saved to an SQLite database. Each case includes:

• The flagged message and which category caught it
• 20 messages of chat before and after it
• The player's past offense history
• A log of all staff actions taken on it

Staff can open the case list in-game with /gavelry cases or /gvl cases and handle everything from there.

---

Pattern Lists

Word lists are plain .txt files, one term per line. Gavelry ships with built-in lists for all four categories. You can also point a category at a remote URL and Gavelry will fetch it on startup and on each reload.

Two files let you adjust any category without editing the base lists:

• custom-additions.txt adds terms to every category
• custom-exclusions.txt removes terms from every category

Run /gvl reload to pick up changes without restarting.

---

Integrations

Discord Webhook - new cases get posted to a staff channel. You can set a minimum severity so only serious violations (like slurs or advertising) are sent.

LuckPerms Trusted Groups - players in trusted groups skip profanity and spam checks but are still filtered for slurs.

---

Commands

Command	What it does
/gvl reload	Reload config and pattern lists
/gvl cases	Open the case review GUI
/gvl stats	View filter statistics
/gvl mute <player> <duration> <reason>	Mute a player manually
/gvl unmute <player>	Unmute a player
/gvl history <player>	View a player's past cases

All commands work with both /gavelry and /gvl.

gavelry.bypass is not given to OPs by default. Server owners are filtered the same as everyone else unless the permission is granted explicitly.

---

Credits

_{LEAD DEVELOPER}
(@efegorkemefe) arikutov2

Thank you to everyone who tested and reported bugs.