Installation¶

Requirements¶

Component	Current requirement
Server	Paper
Stable Minecraft versions	Paper 1.21.11, 26.1, and 26.2
Preview Minecraft version	Paper 26.3 alpha; startup-tested, not stable support
Java	Java 21 for Paper 1.21.11; Java 25 for Paper 26.1+
Required plugins	None
Optional plugins	LuckPerms, Vulcan
Optional services	Supabase, BetterPunish-compatible Discord companion endpoint

BetterPunish is compiled against the Paper API and uses Paper's asynchronous chat event. A Spigot-only server is therefore not supported by the current code.

Install the plugin¶

Stop the Paper server.
Place the BetterPunish .jar in the server's plugins/ directory.
Start the server with the Java version required by Paper: Java 21 for Paper 1.21.11, or Java 25 for Paper 26.1 and newer.
Confirm that plugins/BetterPunish/config.yml and plugins/BetterPunish/data/ are created.
Review config.yml before giving moderators access.
Run /punishreload after supported configuration changes, or restart the server.

Note

The distributed file name may include a version. The plugin name and data directory are BetterPunish.

Compatibility notes¶

LuckPerms and Vulcan are soft dependencies. BetterPunish starts without them.
LuckPerms is only required when mute-group-sync.enabled is enabled.
Vulcan is detected at runtime. If neither supported Vulcan event class is present, the integration is skipped.
Supabase and Discord are disabled while their shipped placeholder values remain unchanged.

See the compatibility matrix for exact tested Paper builds and the distinction between stable and preview verification.

First-start check¶

After startup, verify:

the console reports that BetterPunish enabled without an exception;
/punishgui opens for an operator;
/punishreload reports that configuration and data were refreshed;
the default Discord invite and companion endpoint have been replaced or deliberately left unused;
moderators have explicit permissions rather than broad operator access.

Continue with the quick start.