Network Setup

Each punishment mutation, removal, modification, rollback and expiration writes its outbox event in the same transaction as the punishment and audit change. A shared InnoDB row serializes event-producing transactions and ladder decisions, ensuring a later event ID cannot commit before an earlier event ID. Login/name/IP observations use independent transactions, avoiding that network mutation lock.

Nodes poll an indexed event ID range in batches of 256. Default propagation is one 500 ms polling interval plus database and scheduler latency. New enforcement is published before superseded cache entries are removed, preventing a transient unban/unmute gap. Player enforcement uses UUID/IP indexes in an active-only cache. GUI history queries load one page and a count, rather than lifetime rows. There is no periodic scan of all players.

Login checks use current database state and fail closed on connection/query timeouts. Chat and blocked commands fail closed once synchronization is more than 10 seconds stale. HikariCP reconnects failed connections. After a database failure, a node replaces its active cache and lockdown state from an authoritative transaction snapshot before reporting healthy again; it enforces current bans against connected players. Obsolete outbox notifications during an outage are not replayed on recovery. Kicks, broadcasts and webhook delivery during an outage should therefore not be treated as guaranteed durable notifications. Permanent ban/mute state remains durable.

The outbox is retained for 30 days. Restarting nodes snapshot current active state instead of replaying old kicks. SQL executors are bounded and reject overload instead of running database work on a caller/game thread. Every query uses prepared statements; only validated configuration identifiers and fixed implementation SQL fragments are concatenated.

Folia player messages, command replies, permission snapshots, disconnects and client command updates use entity schedulers. Console dispatch and command-map changes use the global region scheduler. The engine does not access Bukkit player state from its database workers.

Scopes: GLOBAL, LOCAL (normalized to the issuing node's server name), a specific backend, or a configured server group. Backend names and scope comparisons are case-insensitive. Local restrictions are checked during proxy transfers as well as backend login. ban-alts defaults to DISABLED; NORMAL uses latest IP associations, and ENHANCED uses recent historical associations. These modes deny associated accounts without creating another punishment. Shared addresses are relationships, never proof of common ownership.

Installation and delivery

Requires Java 21 or newer. Install the supplied WrongPunish JAR.

1. Place the JAR in each backend's plugins folder. Use Paper, Purpur or Folia 1.21.11. Older 1.21 releases are not certified.
2. Optionally install the same JAR on Velocity 3.4+ or BungeeCord 1.21. Each platform reads its own entry point.
3. Start once to generate config.yml, templates.yml, webhooks.yml, locale/EN.yml and ten files under guis/.
4. Set a unique network.server-name per node. Use the proxy's actual backend names for scopes and groups. For a network, configure the same MySQL/MariaDB database and table prefix on every node.
5. Configure staff permissions, preferably with LuckPerms. Backend operators receive command, bundled-template and notification permissions by default. Ordinary players can inspect their own /warnings. The wildcard and punishment exemptions/bypasses require explicit grants. An explicit LuckPerms denial overrides an individual operator default; console is highest authority.
6. Restart for initial setup. /wrongpunish reload validates the main configuration, templates, webhooks, selected locale and every GUI file before applying changes. Open GUIs close on a successful reload. Database pools are reused when their settings are unchanged.

SQLite is for a standalone server. Do not share SQLite files over a network filesystem. MySQL/MariaDB tables use InnoDB and utf8mb4.

The plugin uses platform-authenticated UUIDs and platform-provided addresses. It does not decode its own forwarding protocol. Configure Velocity modern forwarding (opens in a new tab) and protect backend access. Bungee forwarding likewise requires protected backend ports. Leave online-mode: true for a properly authenticated proxy network even though backend server.properties may use offline mode.

Install the backend adapter on every backend for normal chat and backend command mutes. Modern signed chat must be cancelled at the backend. The proxy adapters enforce login/transfer bans, kicks, lockdown and proxy commands. They intentionally do not cancel signed normal chat at the proxy. broadcasts.delivery: BACKEND prevents duplicate broadcasts and warning messages when both adapters are installed. Use PROXY for proxy-delivered notices, or ALL to explicitly allow both.