Templates and ladders

Three moderators typing their own reasons produce three spellings of the same offence, three durations, and a history that is hard to read six months later. A template makes Cheating mean one thing.

They also feed the punish GUI and tab completion, so a template you add today shows up everywhere staff punish from.

Templates are grouped by punishment type: ban, mute, kick, warn, unban, unmute, unwarn. The groups are fixed. The entries inside them are yours.

templates:
  ban:
    General-Cheating:
      duration: 30d
      reason: Cheating
      proof-required: false
      global-broadcast:
        enabled: true
        message: "<newline>{meta_prefix_negative}<color:{color_positive}>{victim_name} was banned for Cheating</color><newline>"

The entry key (General-Cheating) is the ID staff type. The reason is what gets stored on the record. They are deliberately separate: a short ID is quick to type, and a readable reason is what appears on the ban screen.

Put the ID where a reason would go:

/ban Steve General-Cheating

Matching is loose. general-cheating, General Cheating, and general_cheating all resolve to the same entry, so staff do not have to remember your capitalisation.

Anything in the command overrides the template. /ban Steve 7d General-Cheating uses the template's reason and broadcast with a seven-day duration instead of thirty.

To restrict staff to templates only, withhold blazebans.reason.custom. Free text is then refused and only template IDs work.

global-broadcast sends a message to every player, not just staff. That is separate from the normal staff broadcast, which always happens unless the punishment is silent.

Most shipped templates have it turned off. Turning it on for serious bans, and leaving it off for routine mutes, is the usual pattern: a public ban announcement is a deterrent, a public mute announcement is noise.

Messages use MiniMessage and support the punishment placeholders. {victim_name}, {staff_name}, {punishment_reason}, {punishment_duration}, {punishment_id}, and the {color_*} and {meta_prefix_*} theme values are all available. Build them in the MiniMessage editor if you would rather see the result than guess.

Run something else when a template is applied:

templates:
  ban:
    Major-Exploits:
      duration: 60d
      reason: Major Exploits
      console-commands:
        - "say {victim_name} was removed for exploiting"
        - "co rollback u:{victim_name} t:7d"

Placeholders are filled in first. A leading slash is optional. Commands run from console, so they are not limited by the issuing staff member's permissions, which is worth remembering before adding anything destructive.

Set proof-required: true on a template to force evidence:

templates:
  ban:
    General-Cheating:
      duration: 30d
      reason: Cheating
      proof-required: true

This is off globally by default and has to be enabled in settings.yml:

experimental:
  proof-requirements:
    enabled: true

It ships disabled because it blocks a punishment mid-incident when a moderator is dealing with something urgent. Turn it on when your team is used to collecting evidence first. Staff with blazebans.proof.bypass are unaffected.

The unban, unmute, and unwarn groups work the same way and provide consistent revoke reasons:

templates:
  unban:
    Appeal-Accepted:
      reason: Appeal accepted
      global-broadcast:
        enabled: false
        message: "<newline>{meta_prefix_negative}<color:{color_positive}>{victim_name} was unbanned</color><newline>"

Used the same way:

/unban Steve Appeal-Accepted

They take no duration, since there is nothing to expire.

A ladder is an ordered list of steps for one kind of offence. BlazeBans counts how many of the ladder's steps the player has already received and applies the next one.

ladders:
  Cheating:
    - type: BAN
      duration: 30d
      reason: Cheating (1st Offense)
      global-broadcast:
        enabled: true
        message: "<newline>{meta_prefix_negative}<color:{color_positive}>{victim_name} was banned for Cheating</color><newline>"
    - type: BAN
      duration: 60d
      reason: Cheating (2nd Offense)
    - type: BAN
      duration: permanent
      reason: Cheating (3rd Offense)

Steps take the same fields as templates, plus a required type: BAN, MUTE, KICK, or WARN. A ladder can mix them, which is the common case:

ladders:
  Spam:
    - type: WARN
      reason: Spam (1st Offense)
    - type: MUTE
      duration: 1h
      reason: Spam (2nd Offense)
    - type: MUTE
      duration: 1d
      reason: Spam (3rd Offense)
    - type: BAN
      duration: 7d
      reason: Spam (4th Offense)

/punish Steve Spam

BlazeBans reads Steve's history, counts records matching this ladder's steps by type and reason, and applies the step at that index. Past the last step, it stays on the last step, so a permanent ban does not roll over into nothing.

Because matching is by type and stored reason, each step needs a distinct reason. Two steps both reading Spam would count as the same offence and the ladder would never advance. That is why the shipped ladders number their reasons.

/punish needs blazebans.command.punish. When a ladder step is a serious punishment, staff get a confirmation dialog naming what is about to happen before it is applied.

It also accepts a plain template ID, not just a ladder, which applies that template once with no escalation. That means staff can use one command for everything rather than switching between /punish and /ban depending on what they are applying.

templates.yml reloads with:

/blazebans reload templates.yml

Tab completion refreshes for online players automatically after a template reload, so new templates appear without anyone relogging.