Wardly: Minecraft Ban, Mute & Punishment Plugin

Wardly is a free, open-source ban / mute / kick / punishment management plugin for Minecraft servers and networks, built for Velocity, Paper (standalone) and Paper backends behind a Velocity proxy. It's a full moderation toolkit: durations, reason presets, staff permission groups, GeoIP-based ban-evasion detection, automatic multi-language translation of ban reasons, and a REST API for an external web admin panel.

Features

• Punishments: /ban, /ipban, /mute, /kick, /unban, /unmute with human-readable durations (7d, 2h, 30m, permanent) and free-text or preset reasons.
• Staff permission groups: per-group duration caps, granular per-command permissions and admin/super-admin tiers, configured in groups.yml.
• Reason presets: reusable, tab-completable ban/mute/kick reasons with per-language text, custom disconnect screens and automatic "ban-evading" alt detection (presets.yml).
• Ban evasion detection: alerts staff when a joining player shares an IP with an existing banned account.
• GeoIP: resolves a player's country/ISP for staff (/geoip, /dupeip) and to auto-detect their language.
• Multi-language: built-in messages in English, Italian, French, Spanish and German, plus optional automatic translation (DeepL / Google) of free-typed ban reasons.
• /wardly staff panel: paginated ban/mute/kick lists, search, per-staff statistics, lookup, force-expire, wipe and purge tooling.
• REST API: a built-in HTTP admin API (players, bans, mutes, logs, GeoIP, ban-by-code lookup, admin ban/kick/unban) for building an external web dashboard, no extra dependencies, no framework, just com.sun.net.httpserver.
• MySQL storage via HikariCP, single schema shared across every deployment mode below.

Commands

Durations accept 7d, 2h, 30m or permanent. Reasons can be free text or a preset key from presets.yml. Every command respects the caller's group permissions and duration caps (groups.yml).

Command	Description
/ban <player> [duration] <reason>	Ban a player, online or offline
/ipban <player> [duration] <reason>	Ban a player's IP address, disconnecting every account sharing it
/unban <player>	Remove an active ban or IP-ban
/mute <player> [duration] <reason>	Silence a player in chat
/unmute <player>	Remove an active mute
/kick <player> <reason>	Immediately disconnect a player
/checkban <player>	Show a player's active ban, if any
/checkmute <player>	Show a player's active mute, if any
/banreason <player> <reason>	Edit the reason of the most recent active ban
/bantime <player> <duration>	Edit the duration of the most recent active ban
/banlist [page]	Paginated list of active bans
/history <player> [page]	Full punishment history for a player
/dupeip <player>	List accounts that share the player's IP
/geoip <player>	Resolve a player's country/ISP
/wardly	Staff panel: list, active, recent, top, lookup, search, stats, groups, checkgroup, staffhistory, staffstats, expire, wipe, purgedata, reload

Deployment modes

Wardly is a multi-module Gradle project. Pick the module(s) that match your setup: you never need more than one.

Setup	What to install	Config lives in
Network (Velocity + multiple backend servers)	velocity on the proxy, spigot-network on every Paper backend	proxy only, backends need zero config or database
Standalone (single Paper server, no proxy)	spigot-standalone alone	that server's own plugins/Wardly/ folder
Velocity only (no backend plugin)	velocity alone	proxy (works, but see note below)

Network mode

spigot-network is a thin client: no config file, no database connection. Mute state and a player's resolved language are pushed to it live from the proxy over plugin-messaging (wardly:mute, wardly:lang). Commands and ban enforcement never need to run on the backend: Velocity intercepts its own registered commands network-wide, and bans are already denied at login before a player ever reaches a backend server. This design keeps configuration and the database in exactly one place: the proxy.

Standalone mode

spigot-standalone is the full plugin, with the same commands, enforcement and REST API as velocity, for admins running a single Paper server with no proxy. It owns its own plugins/Wardly/config.yml and MySQL connection. It will log a warning on startup if it detects the server has Velocity/BungeeCord IP forwarding enabled, since that usually means you actually want spigot-network instead.

Velocity-only note

Minecraft's chat-signing protocol means a proxy can't always deny an already-signed chat message, so /mute enforcement on Velocity alone can occasionally miss a message. Pair velocity with spigot-network on your backends for fully reliable mute enforcement.

Building

./gradlew build

Each module produces its own jar under <module>/build/libs/:

• velocity/build/libs/velocity-*.jar → proxy plugins/
• spigot-standalone/build/libs/spigot-standalone-*.jar → standalone server plugins/
• spigot-network/build/libs/spigot-network-*.jar → backend server plugins/

Requires Java 21 and a MySQL/MariaDB database reachable from wherever you deploy velocity or spigot-standalone.

Project structure

core/               platform-agnostic business logic: commands, punishment/database/config
                     managers, localization, REST API. Shaded into velocity and spigot-standalone.
velocity/            Velocity proxy plugin (bootstrap, listeners, plugin-messaging bridges).
spigot-standalone/   full Paper plugin for single-server setups.
spigot-network/      thin Paper client for backends behind a Wardly-enabled Velocity proxy.

License

MIT: free to use, modify and self-host.

---

Keywords: minecraft ban plugin, minecraft punishment plugin, minecraft moderation plugin, velocity ban plugin, spigot ban plugin, paper ban plugin, minecraft mute plugin, minecraft kick plugin, minecraft staff tools, minecraft admin plugin, minecraft geoip ban, minecraft network punishment system.