PunisherX add-on for Velocity server network for instant cross-server syncing of penalties like kicks and bans
PunisherX Velocity Bridge
One network. Shared bans. Moderation that follows the player.
Download · Quick start · Configuration · Documentation · Discord
PunisherX Velocity Bridge connects your Velocity proxy to the PunisherX installation on your backend servers. A ban issued from one backend can disconnect its target elsewhere on the network, even when the command runs from the console on an empty server.
Install the bridge on the proxy, alongside the full PunisherX plugin on your Paper/Folia or Spigot backends. Both use the same MySQL database.
✨ Network moderation
| Feature | What it does |
|---|---|
| Cross-server bans | Disconnects a player by UUID when a BAN event reaches the proxy. |
| IP ban events | Disconnects connected players whose IP matches a BANIP event. |
| Persistent event queue | Polls the shared bridge_events table, so events can arrive even from an empty backend. |
| Backend messages | Also receives BAN and BANIP through the punisherx:bridge plugin messaging channel. |
| Login and transfer checks | Checks active network-wide UUID bans at login and before connecting to a backend. |
| Clear disconnect messages | Shows the punishment type, reason and remaining duration, including permanent bans. |
The bridge handles BAN and BANIP events. Login and backend transfer checks currently query UUID-based BAN records with server = network; they do not query active IP bans. Other punishments, such as mute, warn and jail, are handled by PunisherX on the backend servers.
📦 Download
Download PunisherX-Velocity-Bridge-<version>.jar from GitHub Releases when available. Development artifacts are available from successful build workflow runs.
Looking for the backend plugin or the BungeeCord artifact? See the main PunisherX README.
⚙️ Requirements
| Component | Requirement |
|---|---|
| Proxy | Velocity 4; the current project targets 4.2.1-SNAPSHOT. |
| Java | 25 or newer on the proxy. |
| Backend plugin | PunisherX for Paper/Folia or Spigot. |
| Storage | A shared MySQL database, reachable from the proxy and backends. |
| Database access | Read punishment records; read/write bridge events; create bridge_events if it is absent. |
🚀 Quick start
- Install PunisherX on your backend servers and configure them to use the shared MySQL database.
- Place
PunisherX-Velocity-Bridge-<version>.jarin the proxy'splugins/directory. - Start the proxy once to generate
bridge.propertiesin the bridge's plugin data directory. - Set the database connection in that file to the same database used by PunisherX on the backends.
- Restart the proxy to load the connection settings.
- Configure network-wide punishment scope on the backends, following the administrator guide.
🔧 Configuration
The bridge reads bridge.properties. Example:
host=localhost
port=3306
database=punisherx
username=punisherx
password=replace_with_your_database_password
poll-interval-ms=1000
| Setting | Meaning |
|---|---|
host / port |
Address of the shared MySQL server. localhost refers to the machine running the proxy. |
database |
The database containing PunisherX's punishments and bridge_events tables. |
username / password |
Credentials with access to those tables. |
poll-interval-ms |
Queue polling interval in milliseconds. Default: 1000; values below 200 are clamped to 200. |
Match the backend's database.sql.* connection settings. Credentials can differ if both database users have the required access to the same database. Restart the proxy after editing this file.
🔄 How it works
- PunisherX writes a
BANorBANIPevent to the sharedbridge_eventstable. - The proxy bridge polls unprocessed events at the configured interval and disconnects matching connected players.
- Each handled event is marked as processed, so later polls skip it.
- Independently, login and backend transfer checks read active network-wide UUID bans from
punishments. Processing a queue event does not remove the corresponding punishment.
For example, a moderator on Survival bans a player currently on Lobby. The bridge reads the event and disconnects that player from Velocity. If the UUID ban is stored with network scope and remains active, the login check disconnects the player when they try to return.
🛠️ Troubleshooting
| Symptom | Check |
|---|---|
| Database connection fails | Host, port, credentials, database access and connectivity from the proxy. |
| A ban does not reach the proxy | Both sides must use the same database; verify that the backend creates a bridge_events entry. |
| A UUID ban does not block rejoining | The record must have punishmentType = BAN, server = network and an active expiry, or endTime = -1 for a permanent ban. |
| An IP-banned player can reconnect | Active IP bans are not checked by the bridge's login query; backend enforcement still needs to be configured. |
| Changes to connection settings have no effect | Restart the proxy after editing bridge.properties. |
🧱 Build from source
From the repository root:
./gradlew :punisherx-velocity-bridge:build
Use a Java 25 toolchain. The resulting plugin JAR is written to punisherx-velocity-bridge/build/libs/.
📚 Links
Licensed under the MIT License. Created by SyntaxDevTeam.
Pinned Versions
- R4.0.0–4.2.1
Pages
Members
1
Owner