PunisherX-Velocity-Bridge

PunisherX Velocity-Bridge

PunisherX Velocity-Bridge is a lightweight addon for Velocity 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 Velocity-Bridge solves this problem.

The addon acts as a bridge between:

• PunisherX on Paper/Folia (where punishments are executed),
• Velocity Proxy (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. Velocity-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-Velocity-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 addon (bridge), not a standalone punishment system. It requires the main PunisherX plugin on Paper/Folia and a shared database to function.