Getting Started

Overview

XBans is the moderation addon for XCore: sanctions, security and chat. It covers bans, mutes, warns and jails, and the tools around them: chat filtering, VPN detection, alt-account analysis and a staff toolkit.

Key highlights:

Unified sanctions — Ban, mute, warn, report, and jail with temporary or permanent durations
IP-level enforcement — IP bans, IP mutes, CIDR range blocking, and ISP blocking
Chat moderation — A word list that survives any way of disguising a word, plus a trained classifier for the phrasing a list cannot anticipate
Security suite — VPN and proxy blocking, client brand filtering, protocol version control, and alt-account detection
Staff tools — Freeze, watchlist, staff notes, warden notifications, and detailed player profiles
Point-and-click moderation — Fully customizable YAML-driven GUI screens, including a categorised /punish menu with sub-menus for sanction durations and reasons
Offline sanctions — Ban, mute, or warn players who have never connected; the sanction is enforced the moment they first join
Discord integration — Webhook notifications for all sanction events
Web dashboard — REST API module for the XCore web panel
Cross-server sync — All sanctions sync instantly across your network via XCore

Requirements

Paper 1.21.1+ (or Folia)
Java 21+
XCore 1.1+ installed as a plugin
Optional: IPInfo API token for VPN/proxy detection
Optional: Discord webhook URL for sanction notifications

Installation

Install XCore in your server's plugins/ folder if you haven't already.
Place XBans.jar in plugins/XCore/addons/.
Start the server. XBans generates its configuration files in plugins/XCore/addons/XBans/.
Edit config.yml to configure your moderation preferences, API keys, and feature toggles.
Customize lang/<code>.yml to match your server's language and style.
Restart the server or use /xbans reload to apply changes.

XBans creates its database tables automatically on first startup. If you're using MySQL/MariaDB through XCore, all sanctions are stored centrally and can be synced across servers.

Grant yourself xbans.admin to access all features, or assign granular permissions per command for your staff team.

Proxy mode (Velocity / BungeeCord)

The same jar is also a proxy plugin. Drop XBans.jar in the proxy's own plugins/ folder and a banned player is turned away there, instead of being handed to a backend that kicks them a moment later — which also covers a backend that does not run XBans at all.

Copy XBans.jar into the proxy's plugins/ folder (in addition to plugins/XCore/addons/ on each backend).
Start the proxy once: it writes plugins/XBans-Proxy/proxy-config.yml and proxy-lang.yml.
Fill in the database section with the same database your backends use.
Restart the proxy. The pool and the JDBC driver are downloaded on that first start.

Mechanic	Behaviour
Source of truth	The same tables your Paper servers write. No second ban list, no synchronisation to set up
Freshness	No cache: two indexed lookups per login, so a ban takes effect on the very next connection
Scope	Only network-wide sanctions. A ban scoped to one server stays that server's business
Database unreachable	The connection is let through rather than the network being closed — the backend still checks
Databases	MySQL/MariaDB or PostgreSQL
Kick screens	`proxy-lang.yml`, in legacy colour codes (the one dialect both proxies understand)

A SQLite network cannot share its file with the proxy, which is a different process on a different machine. Leave the plugin off the proxy there — the backends already enforce every sanction.