[![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. | | **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` — 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 — 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. 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

Click to expand the full config.yml

```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 # 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` | | — | `bansys.notify` *(receives alt-account/VPN staff alerts)* | | — | `bansys.bypasschatfilter` | | — | `bansys.bypasschatdelay` | | — | `bansys.ban.bypass` *(suppress kick-on-ban)* | --- ## 🧩 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 | Discord: [dc.gg/paperstream](https://dc.gg/paperstream) Open source under the MIT License. Source: [GitHub](https://github.com/LucasTHCR/EmpireBan)

EmpireBan

1.0-RELEASE