Installation

• Java 21 or newer. Check with java -version on the machine running the server.
• Paper 1.21 or newer, a Folia build, or Velocity.
• On Paper and Folia, outbound internet access the first time it starts.

On Paper and Folia, BlazeBans downloads the supporting libraries it needs on first start, mainly the database drivers. It only happens once; the server keeps them afterwards. If your host blocks outbound connections, allow repo.papermc.io and Maven Central before starting.

Velocity does not support that, so the Velocity jar ships with everything already inside it. It is noticeably larger as a result, and it needs no download to start.

1. Stop the server.
2. Drop BlazeBans.jar into plugins/.
3. Start the server.
4. Watch the console. BlazeBans prints its version, platform, and storage backend as it comes up.

On the first start it writes plugins/BlazeBans/ with settings.yml, database.yml, templates.yml, menus.yml, automod.yml, discord.yml, import.yml, and a messages/ folder. Nothing else is needed to use it.

Confirm it loaded:

/blazebans version

That prints the running version, the platform it detected, and the storage backend in use. If the storage line does not say what you expect, read Database.

Folia uses the same jar. There is no separate download and nothing to switch on.

1. Stop the proxy.
2. Drop BlazeBans-Velocity.jar into the proxy's plugins/.
3. Start the proxy.

The Velocity build enforces bans at connection time and provides the punishment and lookup commands under one root command rather than as top-level commands. See Command reference for which commands exist on which platform.

Three checks, in order:

/blazebans version
/blazebans permissions
/ban NotARealPlayer 1m Test

The first confirms it started. The second confirms your account is recognised as an administrator and lists every permission node. The third confirms writes reach the database; revoke it afterwards with /unban NotARealPlayer.

If the third command reports a storage error, the plugin has started but cannot write. Go to Database.

On a network, punishments only travel between servers if the servers share a database.

1. Create one MySQL, MariaDB, or PostgreSQL database.
2. On every install, set the same credentials in database.yml.
3. On every install, set a distinct server.id in settings.yml.
4. Decide whether punishments default to global or server scope, and set server.scope accordingly.

SQLite is a local file and cannot be shared between servers, even on the same machine. If two servers point at the same SQLite file, expect corruption.

Scope is the part worth reading properly before staff start punishing, because changing it later does not rewrite existing records. See Servers and scope.

Replace the jar and restart. Configuration is never overwritten.

Each config file carries a meta.version. On start, BlazeBans compares it to the version it ships and adds any keys that are new, leaving your existing values alone. New message keys fall back to English until you translate them.

Update checking is on by default and reports to anyone with blazebans.update.notify or blazebans.admin. Only the plugin name and version are sent. Turn it off in settings.yml:

updates:
  enabled: false