Compatibility
Minecraft: Java Edition
Platforms
Tags
Creators
Details
EmpireBan
Your server. Your rules.
A configurable ban/mute/kick system with escalating punishment IDs, staff notes, a smart chat filter with violation points, alt-account detection via IP, and VPN/proxy checking - for Spigot/Paper, BungeeCord, and Velocity, shipped as a single JAR.
Features
| Feature | Description |
|---|---|
| Ban/Mute/Kick/Warn | Full punishment system with per-player history. |
| Configurable Escalation IDs | Define any number of named punishment reasons (ids.yml), each with its own escalation levels - 1st offense, 2nd offense, and so on, capped at the harshest configured level once exhausted. |
| Alt-Account Detection | Flags staff or auto-bans players who join from the IP of a currently banned player. |
| VPN/Proxy/Tor Check | Optional lookup via vpnapi.io on join. |
| Chat Filter & Slowmode | Blacklist words/links and enforce a configurable chat delay, both with bypass permissions. |
| Smart Content Filter | Catches leet speak (sh1t) and accented spellings, matches whole words so ass never hits class, supports regular expressions, per-word weights, local word files and remote word lists. Checks chat, commands and (on Spigot) signs. |
| Violation Points | Every match is worth points that decay over time. Stages in stages.yml warn, mute or ban automatically, or run console commands. |
| Command Blocker | Optional block and allow lists for commands, namespaced forms like minecraft:op included. |
| Staff Notes | /note <player> <text> (or /ban note ...) leaves an internal note that shows up in /history. |
| Export | /bansystem export writes punishments, logs, notes or filter violations as JSON or CSV, optionally limited to the last N days. IP addresses are never exported. |
| Import | /bansystem import takes over bans, mutes, kicks, warnings and notes from LiteBans, AdvancedBan (both via MySQL) and the vanilla ban lists, with a dry run first. |
| Redis Sync | Optional. A ban on one proxy throws the player off every other proxy within a second. /bansystem sync shows the state. |
| Config Upgrades | New options are added to your config.yml on update, with their comments, and nothing you changed is touched. A config.yml.bak is kept. |
| Mutes That Actually Hold | Muted players are also kept off /me and the private message commands, configurable per command name. |
| ID-Only Mode | Optionally refuse free durations on /ban and /mute so every punishment goes through a configured ID - with an opt-out for admins. |
| MySQL or SQLite | HikariCP-pooled MySQL, or zero-config SQLite by default. |
| Action Logs | Every punishment and revocation is logged, viewable and clearable in-game. |
| Discord Webhook | Every ban, mute, kick, unban and unmute posted to a Discord channel, optionally filtered by action. |
| PlaceholderAPI | %empireban_points%, %empireban_stage%, %empireban_muted% and %empireban_mute_remaining% (Spigot, optional). |
| English and German | Both message files ship with the plugin; switch with language: german. |
| Single Cross-Platform JAR | One EmpireBan.jar - each platform only reads its own entry point and ignores the rest. |
Dependencies
- Spigot / Paper, BungeeCord, or Velocity -
required(exactly one, depending on where you run it) - vpnapi.io -
optional- vpnapi.io (free tier: up to 100 lookups/day) - PlaceholderAPI -
optional(Spigot only) - Redis -
optional(only for the sync between several proxies)
How It Works
EmpireBan ships as a single JAR containing all three platform integrations. On load, each platform only reads its own entry point - Spigot reads plugin.yml, BungeeCord reads bungee.yml, Velocity reads the @Plugin-annotated class - and the rest of the JAR is ignored.
Proxy setups: install the JAR only on the proxy (Velocity or BungeeCord), not on the Spigot backend servers as well. It only belongs on a Spigot server in a pure standalone setup with no proxy in front.
Punishments are organized around IDs - named, reusable reasons like griefing or cheating - each with an ordered list of escalation levels. A player's Nth punishment under a given ID applies that ID's Nth level (capped at the last level once every level has been used), so a first offense might warn, a second mute, and a third ban - fully configurable per ID. /ban and /mute both run the same escalation and report the punishment that was actually applied, so an ID whose next level is a ban bans (and kicks) even when it was handed out via /mute.
On join, EmpireBan checks the connecting player's IP against currently banned players and, depending on config, either just notifies staff or automatically bans the alt account too. If VPN checking is enabled, it also queries vpnapi.io for VPN/proxy/Tor usage on that IP.
Configuration
The fully commented files are in the repository (config.yml, stages.yml).
Click to expand the config.yml keys
version: 2
language: english
database:
type: sqlite
mysql:
host: localhost
port: 3306
database: empireban
username: root
password: ''
use-ssl: false
ip-handling:
autoban: false
notify-staff: true
vpn-check:
enabled: false
api-key: ''
autoban: false
chat-filter:
enabled: true
blacklist:
- 'discord.gg/'
- 'http://'
- 'https://'
chat-delay:
seconds: 3
discord-webhook:
enabled: false
url: ''
username: 'EmpireBan'
actions: []
geyser:
support: true
mute-command-blacklist:
enabled: true
list:
- 'me'
- 'msg'
- 'tell'
- 'w'
- 'whisper'
- 'r'
- 'reply'
punishments:
require-id: false
admin-bypass: true
signed-chat-bypass: true
content-filter:
enabled: true
check-chat: true
check-commands: true
check-signs: true
leet-speak-detection: true
unicode-normalization: true
whole-words-only: true
default-weight: 10
words: []
remote-lists: []
regex: []
custom-weights: {}
replace-word-with: '***'
auto-update:
enabled: true
interval-minutes: 60
points:
enabled: true
decay-enabled: true
decay-after-minutes: 30
decay-amount: 5
reset-on-mute: true
command-blocker:
enabled: false
list: []
remote-lists: []
whitelist: []
redis:
enabled: false
host: localhost
port: 6379
username: ''
password: ''
ssl: false
channel: empireban
server-id: ''
import:
litebans:
host: localhost
port: 3306
database: litebans
username: root
password: ''
table-prefix: litebans_
advancedban:
host: localhost
port: 3306
database: advancedban
username: root
password: ''
Click to expand the default stages.yml
stages:
1:
points-threshold: 10
action: warn
2:
points-threshold: 30
action: warn
3:
points-threshold: 60
action: mute
mute-duration: 1800
4:
points-threshold: 120
action: mute
mute-duration: 86400
5:
points-threshold: 200
action: ban
ban-duration: 0
ban-reason: 'Repeated chat violations'
ids.yml holds the configurable escalation-ID system, and messages_english.yml holds every player- and staff-facing message (color codes via &, placeholders). Both are copied into the data folder from the JAR on first start. The structure supports additional messages_<language>.yml files if you want to translate the player-facing messages.
Durations are always stored internally in seconds: 1 day = 86400, 1 year = 31536000, -1 = permanent. Commands additionally accept shorthand like 1d12h, 30m, perm.
Commands & Permissions
| Command | Permission |
|---|---|
/bansystem (alias /bansys) |
bansys.bansys |
/bansystem reload |
bansys.reload |
/bansystem export <punishments|logs|notes|violations> <json|csv> [timespan] |
bansys.export |
/bansystem import <litebans|advancedban|vanilla> [confirm] |
bansys.import |
/bansystem sync |
bansys.sync |
/bansystem ids create <id> <type> <onlyAdmins> <duration> <reason> |
bansys.ids.create |
/bansystem ids delete <id> |
bansys.ids.delete |
/bansystem ids edit <id> add lvl <lvl> <duration> <type> |
bansys.ids.addlvl |
/bansystem ids edit <id> remove lvl <lvl> |
bansys.ids.removelvl |
/bansystem ids edit <id> set lvlduration <lvl> <duration> |
bansys.ids.setduration |
/bansystem ids edit <id> set lvltype <lvl> <type> |
bansys.ids.settype |
/bansystem ids edit <id> set onlyadmins <true/false> |
bansys.ids.setonlyadmins |
/bansystem ids edit <id> set reason <reason> |
bansys.ids.setreason |
/bansystem ids show [id] |
bansys.ids.show |
/bansys logs show [page] |
bansys.logs.show |
/bansys logs clear |
bansys.logs.clear |
/ban <player> <id|duration> [reason] |
bansys.ban.<id> / bansys.ban.all / bansys.ban.admin |
/unban <player> [reason] |
bansys.unban |
/mute <player> <id|duration> [reason] |
bansys.ban.<id> / bansys.ban.all |
/unmute <player> [reason] |
bansys.unmute |
/kick <player> [reason] |
bansys.kick (bypass: bansys.kick.bypass) |
/check <player> |
bansys.check |
/history <player> |
bansys.history.show |
/deletehistory <player> |
bansys.history.delete |
/note <player> <text>, /ban note <player> <text> |
bansys.note |
/note remove <id> |
bansys.note.remove |
/chatfilter info <player> (alias /cf) |
bansys.filter |
/chatfilter history <player> [page], lookup <id>, resetpoints <player> |
bansys.filter |
/chatfilter addword <word> [weight], removeword, listwords |
bansys.filter |
/chatfilter addcmd <command>, removecmd, listcmds |
bansys.filter |
/chatfilter test <text>, stats, update |
bansys.filter |
| - | bansys.notify (receives alt-account/VPN staff alerts) |
| - | bansys.bypasschatfilter |
| - | bansys.bypasschatdelay |
| - | bansys.bypasscommands (exempt from the command blocker) |
| - | bansys.ban.bypass (suppress kick-on-ban) |
| - | bansys.ban.admin (also: use free durations while punishments.require-id is on) |
Known Limitations
- No GUI menu for the ban list - command-driven only.
- Signed chat (Minecraft 1.19.1+) can't be intercepted by BungeeCord/Velocity on their own - that needs the companion Spigot chat adapter on each backend server (
config.yml: signed-chat-bypass), which isn't bundled yet. - BungeeCord cannot hand a changed chat message on to the backend server. A message the content filter would censor is blocked there instead, with the usual notice. Velocity and Spigot/Paper censor in place.
- The sign check of the content filter only exists on Spigot/Paper, a proxy never sees signs.
- LiteBans and AdvancedBan can only be imported from MySQL. Their default storage (H2 and HSQLDB) is a file, so move it to MySQL first.
- Redis only carries the news of a ban. All proxies have to share one MySQL database for the others to find it.
- Geyser support is limited to the
geyser.supportconfig flag; no native Geyser-specific behavior beyond that.
Getting Started
- Drop
EmpireBan.jarinto yourplugins/folder - only on the proxy (Velocity/BungeeCord) if you run one, otherwise on the Spigot server. - Start the server once to generate
config.yml,ids.yml,stages.yml, andmessages_english.yml. - Set your database (SQLite by default, or MySQL) and enable VPN checking if you want it.
- Reload with
/bansystem reload- no restart needed.
Credits
| LucasTHCR | Creator & maintainer |
| NTMFanSolidius | Command blacklist for muted players (#1) |
The content filter, the violation points and the command blocker come from GigaProtect, which has been merged into EmpireBan.
Discord: dc.gg/paperstream
Open source under the GNU General Public License v3.0.


