FAQ

Edit three keys in messages/en_us.yml: ban-screen-permanent, ban-screen-temporary, and kick-screen.

messages:
  ban-screen-permanent:
    kick-screen:
      lines:
        - "<color:{color_negative}>You are banned from this server.</color>"
        - "<color:{color_subtle}>Reason:</color> <color:{color_detail}>{punishment_reason}</color>"
        - "<color:{color_subtle}>Appeal:</color> <color:{color_accent}>{appeal_url}</color>"

Each entry in lines is one line. Available: {punishment_id}, {victim_name}, {staff_name}, {punishment_reason}, {punishment_duration}, {expires}, {server}, {appeal_url}.

Reload with /blazebans reload messages:en_us.yml, note the colon.

Preview it in the MiniMessage editor, which has a ban screen mode that draws exactly what the client will show, including the centring. See Messages and theming.

Ten values at the top of messages/en_us.yml:

meta:
  color-scheme:
    positive: "#3b9dff"
    negative: "#d6242d"
    accent: "#a8d5ff"
    detail: "#d0e8ff"
    text: "#b8b8b8"
    subtle: "#5f5f5f"
    highlight: "#ffffff"

Every message references these, so changing one value changes it everywhere.

Quote your hex codes. positive: #3b9dff unquoted is a YAML comment, which is the most common mistake in this file.

Change the prefix too, under meta.plugin.prefix, or the plugin still announces itself as BlazeBans. See Messages and theming.

Create a webhook in your Discord channel settings (Edit Channel, Integrations, Webhooks, New Webhook) and copy the URL. Then in discord.yml:

enabled: true
webhook-url: "https://discord.com/api/webhooks/000000/your-token"

Reload with /blazebans reload discord.yml and test with /warn YourName Testing.

Use a private staff channel. Posts include player names, reasons, and staff names. See Discord webhooks.

Put the old plugin's database details in import.yml, then run the import.

advancedban:
  type: "mysql"
  mysql:
    host: "127.0.0.1"
    port: 3306
    database: "advancedban"
    username: "advancedban"
    password: "change-me"

/blazebans import advancedban
/blazebans import advancedban confirm

Same shape for LiteBans, under a litebans: key. If the old plugin uses a local file rather than a database server, stop it first: it holds a lock while running.

Back up your BlazeBans database first. Running an import twice is safe, since duplicates are detected. See Importing punishments.

/blazebans editor

Open the link it sends, run the /blazebans trust <code> command it shows you, and edit in the browser. Applying changes writes templates.yml and reloads it, no restart.

Verification exists so a leaked link is useless without server access. See Web editor.

Nothing defaults to true except the two lockdown bypass nodes. Every command node has to be granted.

The minimum useful moderator set:

blazebans.command.ban
blazebans.command.mute
blazebans.command.warn
blazebans.command.kick
blazebans.command.unban
blazebans.command.unmute
blazebans.command.history
blazebans.command.punishgui
blazebans.staff.notify
blazebans.duration.moderator

Full list in Permission reference.

Staff weight. A staff member can only punish someone whose weight is at or below their own, and two moderators on the same rank have the same weight.

Equal weights can punish each other by design. If yours cannot, check for an inherited blazebans.weight.* node, or a group exemption in exempt.luckperms-groups. See Hierarchy and exemptions.

Scope. A punishment issued with server scope applies only on the server it was issued on.

For network-wide bans, either set the default:

server:
  scope: "global"

Or use the flag per punishment:

/ban Steve 30d Cheating --scope server:global

Global scope needs blazebans.scope.global. Every server also has to share one database; SQLite cannot be shared. See Servers and scope.

On a network, usually both.

The proxy denies the connection before the player reaches a backend, which is a cleaner ban screen and one lookup instead of one per server. Backends handle mutes, warnings, chat enforcement, the GUIs, and AutoMod, none of which exist at the proxy layer.

Point both at the same database and give each a distinct server.id.

/punish, in almost every case.

/punish Steve Cheating

It reads the player's history and applies the step your ladder says comes next, so escalation is decided once by whoever writes your rules rather than every time by whoever is online. Staff learn one command instead of command syntax plus duration formats plus your escalation policy.

/ban and the other direct commands are still there for situations your ladders do not cover, or when you are deliberately overriding them.

Configure ladders first, or /punish has nothing to apply. See Best practices and Templates and ladders.

Have it pass --punisher with its own name:

/ban Steve 30d Cheating --punisher Anti-cheat
/punish Steve Cheating --punisher Anti-cheat

Without it, everything automated is recorded as CONSOLE and is indistinguishable from an administrator typing at the server console.

With it, /staffhistory Anti-cheat shows everything that system has issued, /blazebans staffprofile Anti-cheat shows its reversal rate, and /staffrollback Anti-cheat 2h undoes a bad run without touching your moderators' work.

The flag is console only, which is fine because that is how other plugins dispatch commands. Prefer the /punish form so automated punishments escalate on the same ladders your staff use. If the plugin uses the Java API instead, set staffName to the same value.

Withhold blazebans.reason.custom. Free text is then refused and only template IDs work.

Define the templates in templates.yml or through /blazebans editor. They also drive the punish GUI and tab completion. See Templates and ladders.

It is already on. The default muted-commands.blocked list covers vanilla and EssentialsX.

Anything else on your server carrying text between players needs adding by hand: party chat, guild chat, mail, nicknames, and every alias of each.

muted-commands:
  blocked:
    - "party"
    - "p"
    - "guild"
    - "g"

Include the namespaced forms too. Players can run /essentials:msg directly. See Mute enforcement.

With the voice chat addon, yes:

enforcement:
  auto-voice-mute-regular-mutes: true

That is the default once the addon is installed. Without it, a muted player can still talk in voice. See Addons.

IP storage is off by default:

privacy:
  store-ip-addresses: true

Without it there are no addresses on file, so alt lookups, IP punishments, and evasion detection all have nothing to match. Links only appear for sessions recorded after you turn it on.

Read Alts and IP tools before enabling it. IP data is personal data in most jurisdictions.

Probably not, and definitely not as a permanent ban.

It catches siblings, housemates, school networks, and anyone behind shared mobile data. On a server with young players that is a weekly occurrence, not an edge case.

If you do turn it on, use a short duration, write a reason that explains itself, and set a real appeal-url. The alternative is leaving it off and using /alts when something looks suspicious, which takes thirty seconds and catches nobody's brother. See Ban evasion.

Only if more than one server needs to see the same punishments.

One server means SQLite, which is the default and needs no service. A network means MySQL, MariaDB, or PostgreSQL. SQLite is a local file and pointing two servers at it will corrupt it. See Database.

No. Every file carries a meta.version, and on start BlazeBans adds only the keys that are new, leaving your values alone.

Missing keys fall back to shipped defaults, and message files fall back per key to English. Do not edit meta.version yourself.

One: command names and aliases under commands: in settings.yml. Those register at startup.

Everything else applies with /blazebans reload, including templates, messages, menus, AutoMod, Discord, and the storage backend.

Nothing, immediately. A broken file is never applied: the reload is refused and BlazeBans keeps running on the settings it already had.

You get an error naming the file, the line, and what was expected. Fix and reload again.

Yes, in settings.yml under commands.names and commands.aliases. Subcommands nest under their parent.

commands:
  names:
    ban: "punishban"
  aliases:
    ban:
      - "pban"

This needs a restart. See settings.yml.

duration-limits:
  tiers:
    - permission: "blazebans.duration.junior"
      max: "7d"
    - permission: "blazebans.duration.moderator"
      max: "30d"
    - permission: "blazebans.duration.admin"
      max: "permanent"

Grant one node per rank. The highest matching tier wins, and staff holding none are unlimited, which is the part people miss. See Duration limits.

/ban Steve 30d Cheating --silent

Needs blazebans.silent. It suppresses the staff broadcast, the public template broadcast, and the Discord post. The record is still written and still visible in /history.

No. It is marked revoked with who did it, when, and why, and stays in history.

That is deliberate. A second ban reads differently when you can see the first was overturned, and staff behaviour is only reviewable if reversals are on the record too.

/staffrollback BadMod 2h

Revokes every punishment they issued in that window and reports how many it changed.

Check /staffhistory BadMod first to see what falls inside it. There is no undo. See Revoking and editing.

Yes, on the same jar. There is no separate download and nothing to configure.

Paper 1.21 and newer, including Folia builds, plus Velocity. Java 21 or newer.

Native dialogs are used on 1.21.6 and newer. Older servers and clients fall back to chat prompts, which do the same job.

Two outbound connections, both optional.

Update checking sends the plugin name and version, nothing else, and turns off with updates.enabled: false.

The web editor connects to blazestudios.store when you run /blazebans editor, and only then. It never sends license keys, credentials, or the raw config document to the browser.

The BlazeStudios Discord.

Run /blazebans dump first and have the file ready. It records your version, platform, storage backend, and configuration with credentials stripped out, which usually answers the first round of questions before anyone asks them. See Troubleshooting.