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

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)

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

# 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_<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

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

Discord: dc.gg/paperstream

Open source under the GNU General Public License v3.0.