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.