PunisherX-Proxy-Bridge

PunisherX Proxy-Bridge

PunisherX Proxy-Bridge is a lightweight addon for Velocity/BungeeCord networks that synchronizes bans and IP bans from PunisherX (Paper/Folia) via a shared database and instantly disconnects punished players on the proxy.

Description

Do you run a server network and find it frustrating when a player gets banned on one backend but can still stay on the lobby or hop between servers? PunisherX Proxy-Bridge solves this problem.

The addon acts as a bridge between:

* a shared database (where punishments are executed), * a shared database (where the player is actually connected), * a shared database (where punishment events are stored).

When an administrator issues a BAN/BANIP (even from the console and even if the backend is empty), PunisherX records the event in the `bridge_events` table. Proxy-Bridge periodically reads these entries and immediately disconnects matching players on the proxy. After handling, it marks the entry as processed, ensuring the same event is not executed again.

Result: punishments are enforced across the entire network, not just on a single server.

Features

* ✅ Synchronization of BAN/BANIP between PunisherX and Velocity * ✅ Works with punishments issued via commands, console, and offline players * ✅ Immediate enforcement of punishments on the proxy * ✅ Simple configuration (MySQL + polling interval) * ✅ No manual kicking and no bypassing punishments between backends

Requirements

* Java 21+ * Velocity 3.4+ / 3.5+ * PunisherX running on Paper/Folia servers * Shared MySQL/MariaDB database for PunisherX and the bridge

Installation

1. Place `PunisherX-<proxy>-Bridge-<version>.jar` into the `plugins` folder on Velocity. 2. Start the proxy to generate `bridge.properties`. 3. Configure DB credentials (`host`, `port`, `database`, `username`, `password`) identical to PunisherX. 4. (Optional) Set `poll-interval-ms` (default: `1000 ms`, minimum: `200 ms`). 5. Restart Velocity.

Disclaimer

> This is an PunisherX, not a standalone punishment system. > It requires the main PunisherX plugin on Paper/Folia and a shared database to function.