Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
ControlBans
ControlBans is the moderation plugin I enjoy working on the most. I started it in late 2025 and I've been putting it first ever since. More plugins are on the way, but that's a different story.
I built it because I got tired of moderation plugins that put the useful commands behind a premium tier. This one is free and open source, and everything on this page works the moment you drop the jar in. No paid commands, no cut-down version, no catch.
What it does
ControlBans covers the work a moderation team actually has to do: bans, mutes, voice mutes, warnings, kicks, freezes, reports, appeals, notes, alt detection and the staff tools around them.
It runs on Paper 1.21.6 and newer, and on Folia. Java 21. The plugin uses Paper APIs directly, so a server needs Paper or Folia. The same jar also works on BungeeCord and Velocity as a proxy extension, which I'll come back to further down.
Punishment lookups go through a cache and every database call is asynchronous, so a ban never sits on the main thread waiting for a query.
The /punish menu
/punish <player> walks through three screens:
- Category: Chat, Voice, Game or Misc, plus a Legacy presets category if you still have old presets lying around.
- Offence: every offence in that category, with its escalation ladder in the tooltip.
- Tier: the ladder of that offence. The tier that fits the player's own record is marked Recommended, and the number of previous offences shows up on the screen.
Then you type optional notes in chat, or type skip to move on. /punish <player> chat.spamming applies an offence straight away if you'd rather not click through three screens.
On Paper 1.21.6 and newer the menu is a real Minecraft dialog. Everywhere else it falls back to an inventory GUI with the same content. Everything in it comes from config: one accent colour drives the whole interface, every icon is a real item rather than a text character, and on 1.21.9 and newer the dialogs draw actual item sprites and player heads.
Offences and escalation
plugins/ControlBans/offences.yml defines the categories, the offences inside them and how each offence escalates. Nothing is hard-coded. The bundled file gives you 4 categories and 19 offences to start from.
The tier comes out of the target's own history. Punish someone for chat.spamming for the first time and they get tier 0, the second time tier 1, and so on. When the ladder runs out the last tier repeats, so an offence never quietly stops escalating. Strikes expire after a window you set (90 days by default), and an offence can override that with its own.
The tier that was applied is saved next to the punishment, and the stored reason can include the offence name and tier through a template, so the history still explains itself months later.
Staff limits and permissions
Two separate things decide what a staff member can get away with.
Their rank decides how long they may punish for, expressed as plain permission nodes:
controlbans.rank.duration.ban.7d
controlbans.rank.duration.mute.12h
controlbans.rank.unlimited
The biggest bucket they hold wins. A tier above their limit shows up as Locked and the click is refused, so a moderator with a 7 day cap can't hand out a 30 day ban.
Their permissions decide which punishments they may issue at all. /punish checks the same nodes the commands do, so someone without controlbans.tempban sees the ban tiers locked instead of quietly banning people. When a tier mixes an allowed and a forbidden punishment, the allowed one still runs and the other is skipped with a note on the screen. Set punish.require-action-permission: false if you want the old behaviour where controlbans.punish was enough. The console is never restricted.
Commands
Punishments
| Command | What it does |
|---|---|
/ban, /tempban, /unban |
Ban permanently or for a set time |
/mute, /tempmute, /unmute |
Mute permanently or for a set time |
/shadowmute |
The player sees their own messages, nobody else does |
/ipban, /ipmute, /unipban, /unipmute |
Punish by IP address |
/warn |
Warn a player |
/kick |
Kick a player with a reason |
/freeze |
Freeze a player for a screenshare |
/voicemute, /tempvoicemute, /voiceunmute |
Mute players in Simple Voice Chat |
/banskin, /unbanskin |
Force a player's skin back to the default |
/punish |
The three-screen punish menu |
Staff tools
| Command | What it does |
|---|---|
/history |
Full punishment timeline for a player, in a GUI |
/check |
A player's ban and mute status |
/alts |
Accounts sharing an IP, in a GUI |
/note |
Private staff notes on a player |
/banlist, /mutelist |
Browse the active punishments |
/blame |
What a staff member has punished |
/reports |
Report review GUI: full descriptions, filter by status, teleport to either player, resolve, reject, reopen or delete |
/appeals |
Appeal review GUI. Approve one and the player is unmuted |
/chat lock, /chat slow, /chat clear |
Lock chat, set slowmode, wipe chat |
/staff |
Who is online |
/scheduledpunishment |
Schedule a punishment for later |
/bulkpunishment |
Punish a list of players at once, optionally on a schedule |
/controlbans |
Reload, import, export, database and rollback |
For players
| Command | What it does |
|---|---|
/report |
Report a player through a GUI with the categories you configured, or write your own reason |
/reports |
Check the status of your own reports |
/appeal |
Appeal a mute in game |
The punishment commands take -s for a silent punishment. Staff with the silent notify permission see it, everyone else doesn't.
Scheduling, bulk punishments and freeze
Scheduled punishments take relative times (30m, +2h), a wall clock time (23:30), a date and time (2030-01-01 12:00) or a month and day (11-02 23:30). Schedules survive a restart, and clearing them deletes the rows instead of only hiding them.
/freeze <player> locks a player in place for a screenshare. They can't move, break, place, attack, chat or run commands, apart from the ones you allow. The freeze survives a restart, and a frozen player who logs out gets banned. A server shutdown is not treated as a disconnect.
Chat, reports and appeals
/chat lock, /chat slow and /chat clear do what they say. The lock and the slowmode delay are saved, so they survive a restart.
Players report through a GUI with categories you define in the config, or they can write their own reason. Staff get a review GUI with the full description, a click that teleports to either player, and resolve, reject, reopen or delete.
Mutes can be appealed in game. Staff read the appeal and approving it unmutes the player. Cooldown, submission limit and how long the appeal window stays open are all configurable.
Databases and networks
SQLite is the default, so the plugin makes its own file and there's nothing to connect. MySQL and MariaDB are there when you want them, through HikariCP. Expired punishments get cleared on a schedule so the table doesn't fill up with dead rows.
Player lookups are cached, and the cache is invalidated the moment something changes.
The same jar works as a proxy extension too. Drop it into BungeeCord or Velocity and it relays kick messages, broadcasts and staff alerts across the network, and tells the other servers to drop their punishment cache, so a ban on one server lands on the rest.
Integrations
- Simple Voice Chat:
/voicemuteand/tempvoicemutemute players in proximity voice. - Discord: a webhook per punishment type with your own colours, titles, fields and footers, or DiscordSRV if you already run it.
- Floodgate and Geyser: Bedrock players are detected and handled properly.
There's a public API too, if you're writing a plugin of your own and want to hook into bans, mutes and reports.
Look and feel
Every message is MiniMessage and lives in plugins/ControlBans/locales/en.yml, so you can rewrite any of it. The jar ships with theme packs in themes/ that mimic the punishment screens of servers like Hypixel, MineMen and MCPVP, if you want that look without doing the work yourself.
The menu has six presets (arctic, ember, toxic, royal, crimson, mono) and one accent colour that every other shade is derived from.
Translations work the same way. Drop your own file into plugins/ControlBans/locales/ and point language: at it.
Coming from another plugin
/cb import pulls punishments out of LiteBans, AdvancedBan or Essentials. One command and you're over.
Stats
Discord · Source Code · Issues
Images








