[![Discord](https://img.shields.io/badge/Discord-dc.gg%2Fpaperstream-5865F2?style=flat-square&logo=discord&logoColor=white)](https://dc.gg/paperstream) [![Release](https://img.shields.io/modrinth/v/empireban?style=flat-square&label=release&color=00AF5C)](https://modrinth.com/plugin/empireban/versions) [![Downloads](https://img.shields.io/modrinth/dt/empireban?style=flat-square&label=downloads&color=00AF5C)](https://modrinth.com/plugin/empireban) [![Servers](https://img.shields.io/bstats/servers/33126?style=flat-square&label=servers&color=1E90FF)](https://bstats.org/plugin/bukkit/EmpireBan/33126) [![License](https://img.shields.io/badge/license-GPL--3.0-blue?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0.txt) [![Built with Java 21](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/built-with/java21_vector.svg)](https://adoptium.net/) [![Available for Paper](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/supported/paper_vector.svg)](https://papermc.io/) [![Available for Purpur](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/supported/purpur_vector.svg)](https://purpurmc.org/) [![Available for Spigot](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/supported/spigot_vector.svg)](https://www.spigotmc.org/) [![Available for Bukkit](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/supported/bukkit_vector.svg)](https://dev.bukkit.org/) [![Available for BungeeCord](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/supported/bungeecord_vector.svg)](https://www.spigotmc.org/wiki/bungeecord/) [![Available for Velocity](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/supported/velocity_vector.svg)](https://papermc.io/software/velocity) [![Chat with us on Discord](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/social/discord-plural_vector.svg)](https://dc.gg/paperstream) [![Available on Codeberg](https://raw.githubusercontent.com/intergrav/devins-badges/v3/assets/cozy/available/codeberg_vector.svg)](https://codeberg.org/LucasTHCR/EmpireBan)

[![bStats](https://bstats.org/signatures/bukkit/EmpireBan.svg)](https://bstats.org/plugin/bukkit/EmpireBan/33126) # EmpireBan ### *Your server. Your rules.* > A configurable ban/mute/kick system with escalating punishment IDs, 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](https://vpnapi.io/) on join. | | **Chat Filter & Slowmode** | Blacklist words/links and enforce a configurable chat delay, both with bypass permissions. | | **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. | | **Single Cross-Platform JAR** | One `EmpireBan.jar`, and 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](https://vpnapi.io/) *(free tier: up to 100 lookups/day)* --- ## 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. 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, all 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 ```yaml # EmpireBan - Configuration # Time values in this plugin are always stored internally in seconds. # Examples: 1 day = 86400, 1 year = 31536000, -1 = permanent language: english database: # sqlite or mysql type: sqlite mysql: host: localhost port: 3306 database: empireban username: root password: '' ip-handling: # If enabled, players sharing an IP with a banned player are automatically banned too. # If disabled, only the staff team is notified (see notify-staff & the bansys.notify permission). autoban: false notify-staff: true vpn-check: enabled: false # Free key required above 100 joins/day: https://vpnapi.io/ api-key: '' autoban: false chat-filter: enabled: true blacklist: - 'discord.gg/' - 'http://' - 'https://' chat-delay: seconds: 3 geyser: support: true # Commands a muted player may not run - without this, mutes are trivially bypassed via # /me or private messages. Entries are matched against the command name only, with any # "/" and namespace ("minecraft:") stripped. An empty list falls back to the defaults # below; set enabled to false to turn the check off entirely. mute-command-blacklist: enabled: true list: - 'me' - 'msg' - 'tell' - 'w' - 'whisper' - 'r' - 'reply' punishments: # If enabled, /ban and /mute only accept IDs from ids.yml - free durations are refused. require-id: false # Whether staff with bansys.ban.admin (or bansys.ban.all) may still use free durations # while require-id is on. admin-bypass: true # From Minecraft 1.19.1 on, clients sign their chat messages. BungeeCord can't intercept or # cancel signed messages on its own - each backend server additionally needs the included # "BanSystem-SpigotChatAdapter" installed, which forwards chat events to the proxy. signed-chat-bypass: true ``` `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_.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 ids create ` | `bansys.ids.create` | | `/bansystem ids delete ` | `bansys.ids.delete` | | `/bansystem ids edit add lvl ` | `bansys.ids.addlvl` | | `/bansystem ids edit remove lvl ` | `bansys.ids.removelvl` | | `/bansystem ids edit set lvlduration ` | `bansys.ids.setduration` | | `/bansystem ids edit set lvltype ` | `bansys.ids.settype` | | `/bansystem ids edit set onlyadmins ` | `bansys.ids.setonlyadmins` | | `/bansystem ids edit set 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 [reason]` | `bansys.ban.` / `bansys.ban.all` / `bansys.ban.admin` | | `/unban [reason]` | `bansys.unban` | | `/mute [reason]` | `bansys.ban.` / `bansys.ban.all` | | `/unmute [reason]` | `bansys.unmute` | | `/kick [reason]` | `bansys.kick` *(bypass: `bansys.kick.bypass`)* | | `/check ` | `bansys.check` | | `/history ` | `bansys.history.show` | | `/deletehistory ` | `bansys.history.delete` | | (none) | `bansys.notify` *(receives alt-account/VPN staff alerts)* | | (none) | `bansys.bypasschatfilter` | | (none) | `bansys.bypasschatdelay` | | (none) | `bansys.ban.bypass` *(suppress kick-on-ban)* | | (none) | `bansys.ban.admin` *(admin-only IDs, and 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. - Geyser support is limited to the `geyser.support` config flag; no native Geyser-specific behavior beyond that. --- ## Getting Started 1. Drop `EmpireBan.jar` into your `plugins/` folder, **only on the proxy** (Velocity/BungeeCord) if you run one, otherwise on the Spigot server. 2. Start the server once to generate `config.yml`, `ids.yml`, and `messages_english.yml`. 3. Set your database (SQLite by default, or MySQL) and enable VPN checking if you want it. 4. Reload with `/bansystem reload`, no restart needed. --- ## Credits | | | |---|---| | **LucasTHCR** | Creator & maintainer | | **[NTMFanSolidius](https://codeberg.org/NTMFanSolidius)** | Command blacklist for muted players ([#1](https://codeberg.org/LucasTHCR/EmpireBan/pulls/1)) | Discord: [dc.gg/paperstream](https://dc.gg/paperstream) Open source under the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.txt).

EmpireBan

1.1-RELEASE

1.0-RELEASE