All documentation
Documentation

mcBans

Bans, mutes, warnings, kicks and freeze with full history, plus a purgatory mine where banned players can earn their way back. One jar for Paper, Velocity and BungeeCord.

v1.0.1 Paper 1.21.1 or newer (or a Paper fork)Java 21 or newerMySQL or MariaDB (only for networks with a proxy)Vault, PlayerPoints or CoinsEngine (optional)TAB (optional)

Quick start

  1. Put mcBans-1.0.1.jar in plugins/ and start the server. SQLite is used by default and the purgatory world mcbans_purgatory is built for you.
  2. Open plugins/mcBans/config.yml and set punishments.appeal to your appeal link, then run /mcbans reload.
  3. Give your staff the mcbans.staff permission, then run /modpanel to open the control panel.
  4. Try it: /ban <player> 1h Griefing sends the player to purgatory by default. Add -np for a normal ban.
  5. Set store.url and the store.packages entries if you sell credits, and run purgatory give {username} <credits> from your webstore.
  6. Change any message in plugins/mcBans/lang.yml and run /mcbans reload.

#Overview

mcBans is a punishment suite for Paper. It handles bans, mutes, warnings, kicks and freezes, keeps a full history of every action, and adds a twist: instead of a hard ban, a player can be sent to purgatory, a lit mine where they earn credits by mining ore and are released when they reach a goal.

  • Commands and a GUI control panel use the same code, so every action is stored, logged and announced the same way.
  • Records are never deleted. Edits, early endings and reversals are logged with who, when and why.
  • Storage can be YAML, SQLite or MySQL. Networks use MySQL and the same jar on the proxy.
  • Every message is in lang.yml and every option is in config.yml, and most options can be changed in game from the panel.

#Installation and requirements

Requirements

  • Paper (or a fork of it) 1.21.1 or newer. The plugin uses the Paper API, so Spigot is not supported.
  • Java 21 or newer.
  • For a network: Velocity 3.4+ or BungeeCord/Waterfall, plus a MySQL or MariaDB database.
  • Optional plugins: Vault, PlayerPoints or CoinsEngine (to use their balance as purgatory credits) and TAB (for the purgatory tab list).

One server

  1. Put the jar in plugins/.
  2. Start the server. mcBans creates config.yml and lang.yml, uses SQLite by default, and builds the world mcbans_purgatory with a ready-made mine.
  3. Give your staff mcbans.staff (see Permissions).
Same jar everywhere

The one file works on Paper, Velocity and BungeeCord. You do not need a separate download for the proxy.

For a network, see the Network setup section.

#First steps checklist

  1. Set server-name in config.yml. It is saved on every record as the server it was issued on.
  2. Set punishments.appeal to your appeal page. It appears on ban screens. Leave it empty to hide the line.
  3. Decide whether bans should go to purgatory by default (purgatory.default-for-bans, on by default) and how many credits are needed to be released (purgatory.unban-threshold, 10000 by default).
  4. Run /mcbans reload after editing files. Storage and network settings need a full restart.
  5. Run /mcbans info to see the version, storage type, network mode, purgatory location and credit bank in use.
  6. Run /purgatory tp as an admin to look at the Hollow, the cave that was built for you.
Op players

Operators have every permission by default. Players with only mcbans.staff can moderate and open the panel, but cannot reload the plugin, open Settings or manage purgatory. Give mcbans.admin and the purgatory permissions to your admins as well.

#Bans, mutes, warnings and kicks

The commands share one format: the player first, then an optional length, then flags, then the reason. Flags can appear anywhere after the player name.

/ban <player> [length] [-s] [-ip] [-p|-np] [reason]
/tempban <player> <length> [flags] [reason]
/mute <player> [length] [-s] [-ip] [reason]
/warn <player> [-s] [reason]
/kick <player> [-s] [reason]

Lengths

Use units of s, m, h, d, w, mo (30 days) and y (365 days), and combine them: 45s, 2h30m, 7d, 1w2d. Use permanent (also perm, forever or p) for no end. /ban and /mute without a length are permanent. /tempban and /tempmute require a real length.

Flags

FlagMeaning
-sSilent. Only staff with mcbans.notify see the broadcast.
-ipAlso punish the player's IP address. Needs mcbans.ip. Applies to bans and mutes only.
-pSend the ban to purgatory (bans only).
-npMake it a normal hard ban, even if purgatory is the default (bans only).

Good to know

  • If you give no reason, the default from punishments.default-reasons is used.
  • A player has one active ban, one active mute and one active freeze. A new ban or mute replaces the old one and the old record is closed as reversed with a pointer to the new one. A second freeze is refused.
  • /kick and /freeze need the player to be online. Bans, mutes and warnings work on offline players too.
  • Players with mcbans.exempt cannot be banned, muted, kicked or frozen by other staff while they are online. Warnings still work.
  • A hard-banned player sees a multi-line ban screen at login with the reason, staff member, length, time left and your appeal link. It is editable in lang.yml.
  • Muted players cannot chat, and cannot use the commands in punishments.muted-blocked-commands.
  • Reason and length suggestions in tab completion come from the GUI presets in config.yml.

Removing punishments

/unban <player> [-s] [reason]      (alias /pardon)
/unmute <player> [-s] [reason]
/unwarn <player> [id] [-s] [reason]
/unfreeze <player> [-s] [reason]

/unwarn without an id removes the newest active warning. /unban also releases a player from purgatory.

History

/history <player> [page] (aliases /hist, /punishments) shows a player's record in chat, 8 entries per page. Hover a line for every detail. The same record is available in the panel.

#Warning escalation

Warnings can escalate on their own. After each new warning, mcBans counts the player's active warnings. If the count exactly matches a number under warns.thresholds, that punishment is issued by "System".

warns:
  expire-after: "30d"
  thresholds:
    3:
      type: MUTE
      duration: "1h"
      reason: "Reached <count> warnings"
    5:
      type: BAN
      duration: "1d"
      reason: "Reached <count> warnings"
      purgatory: true
  • type is BAN, MUTE, KICK or FREEZE. duration uses the same lengths as commands.
  • purgatory: true sends a ban to purgatory. ip: true also punishes the IP.
  • <count> in the reason is replaced by the number of active warnings.
  • A warning stops counting after warns.expire-after (use permanent to never expire), or when it is removed with /unwarn.
  • Only the exact count triggers a rule. The 4th warning does nothing with the defaults, and each rule fires once per climb.
Defaults

With the default config, 3 warnings give a 1 hour mute, 5 give a 1 day purgatory ban and 7 give a 7 day purgatory ban.

#Editing records and the audit log

Nothing is deleted. Every punishment has an id (shown as #id), and you can change it later:

/mcbans edit <id> reason <text>
/mcbans edit <id> duration <length>
/mcbans expire <id> [reason]     (end it now, kept as Expired)
/mcbans reverse <id> [reason]    (pardon it, kept as Reversed)

All four need mcbans.edit. Each change is written to the audit log with who did it, when and why. The control panel shows the same records and lets you edit them with buttons.

#Freeze

/freeze <player> [length] [-s] [reason] (alias /ss) locks a player in place so you can check them. They stay connected and can still look around, so you can talk to them.

What a frozen player cannot do

  • Move, or be pushed (knockback and other velocity is cancelled).
  • Teleport by pearl, portal or chorus fruit. Staff and plugin teleports still work.
  • Attack, break or place blocks, interact, eat or drink, drop or pick up items, swap hands, enter vehicles, or click in inventories.
  • Chat, or use commands that are not in freeze.allowed-commands.
  • Take damage, if freeze.block-damage is on (default).

They see a title, a boss bar and, if enabled, an action bar. The messages are in the freeze section of lang.yml.

Staff tools

Run /freeze <player> again on a frozen player to open the staff panel:

  • Teleport next to them, or spectate them and return to your old spot.
  • View their inventory (needs mcbans.freeze.inventory).
  • Print their recent chat in your chat. Blocked messages and commands are shown struck through.
  • Open their history, unfreeze them, or open the ban screen.

Logging out while frozen

If a frozen player disconnects by themselves (not kicked), the punishment in freeze.quit-punishment is applied. The default is a permanent ban.

freeze:
  indicator:
    title: true
    bossbar: true
    # PINK, BLUE, RED, GREEN, YELLOW, PURPLE or WHITE
    bossbar-color: BLUE
    actionbar: false
  block-damage: true
  allowed-commands: [msg, tell, r, reply, helpop]
  chat-log-size: 20
  quit-punishment:
    enabled: true
    type: BAN
    duration: "permanent"
    reason: "Logged out while frozen"
    purgatory: false
Edit the boss bar text

The default boss bar mentions a Support voice channel. Change the freeze.bossbar line in lang.yml to match your own server.

#Purgatory

A purgatory ban does not kick the player to a login screen. It sends them to a sealed mine, where they mine ore for credits and are released automatically when they reach purgatory.unban-threshold credits (10000 by default).

How a player ends up there

  • /ban goes to purgatory by default (purgatory.default-for-bans: true) unless you add -np. Use -p to force it when the default is off.
  • Warning escalation rules with purgatory: true.
  • If purgatory.enabled is false, every ban is a normal ban.

What the player experiences

  • They are moved to the purgatory world and given a pickaxe. Right-clicking it opens the upgrade menu.
  • Mined ore pays credits. See "The Hollow and mining".
  • No damage, hunger or death (purgatory.no-damage).
  • Chat is set by purgatory.chat: none, purgatory (they only talk to each other) or staff (only staff with mcbans.purgatory.spy read it). They never see normal chat.
  • With purgatory.hide-others, purgatory players and everyone else cannot see each other, or each other in the tab list.
  • They can only use the commands in purgatory.allowed-commands. Staff with mcbans.purgatory.bypass ignore this list.
  • A boss bar (purgatory.bossbar) and a sidebar scoreboard (purgatory.scoreboard) show the ban reason, staff, length, time left, credits and pickaxe tier. The sidebar lines are in lang.yml.

Release

Reaching the threshold lifts the ban and logs a release by "System". purgatory.release-location is spawn (main world spawn) or last (where the player was before). On a single server, purgatory.save-inventory keeps their inventory while they are inside and gives it back on release. A staff /unban also releases them.

A new purgatory ban starts from 0 credits and tier 1 when purgatory.reset-on-new-ban is on. Lifetime statistics are kept.

purgatory:
  enabled: true
  default-for-bans: true
  unban-threshold: 10000
  reset-on-new-ban: true
  world: "mcbans_purgatory"
  save-inventory: true
  release-location: "spawn"
  chat: purgatory
  hide-others: true
  bossbar: true
  scoreboard: true
  no-damage: true
  allowed-commands: [purgatory, msg, r, tell, reply, helpop, rules]

#The Hollow and mining

On first start mcBans builds the Hollow around 0,0 in the purgatory world: a sealed, lit cave with a deep terraced ore pit, rock pillars, glow vines, amethyst and lanterns, plus a spawn deck. The cave is closed on every side so nobody can leave it.

  • Players can only break ore blocks inside the mine area, and only with the purgatory pickaxe.
  • A mined block turns into bedrock and grows back as a random ore after purgatory.mine.regen-seconds (30 by default).
  • Set purgatory.mine.auto-build: false if you want to use your own build.

Admin setup commands

These need mcbans.purgatory.setup and must be run in game on the server that hosts purgatory:

  • /purgatory tp teleports you to the purgatory spawn.
  • /purgatory setspawn sets the spawn to where you stand (you must be in the purgatory world).
  • /purgatory setmine pos1 then pos2 marks your own ore area.
  • /purgatory refill restores every ore block now.
  • /purgatory rebuild builds the Hollow again. You get a message when it finishes.

Ore values

value is the credits for one block, smelt-value is the credits once the pickaxe has auto-smelt, and weight is how common the ore is when blocks regrow. For "4 coal = 1 credit", set value: 0.25. Any ore you list can be mined, and any block not listed cannot.

ores:
  COAL_ORE:      { value: 0.5,  smelt-value: 0.5,  weight: 40 }
  COPPER_ORE:    { value: 0.75, smelt-value: 1.25, weight: 25 }
  IRON_ORE:      { value: 1.5,  smelt-value: 2.5,  weight: 18 }
  GOLD_ORE:      { value: 3,    smelt-value: 5,    weight: 8 }
  REDSTONE_ORE:  { value: 2,    smelt-value: 2,    weight: 5 }
  LAPIS_ORE:     { value: 3,    smelt-value: 3,    weight: 3 }
  DIAMOND_ORE:   { value: 12,   smelt-value: 12,   weight: 1 }

Pickaxe tiers

Players buy tiers with credits from the same balance that counts toward release, so each upgrade delays freedom a little. Credits per block are (smelt-value if auto-smelt, otherwise value) times fortune-multiplier. efficiency is the Efficiency level, haste the Haste effect level, and radius mines every ore in a cube around the block (0 = one block, 1 = 3x3x3, 2 = 5x5x5).

pickaxe:
  tiers:
    1: { name: "<gray>Rusty",    item: WOODEN_PICKAXE,    cost: 0,    efficiency: 0, haste: 0, fortune-multiplier: 1.0,  auto-smelt: false, radius: 0 }
    2: { name: "<white>Stone",   item: STONE_PICKAXE,     cost: 250,  efficiency: 2, haste: 0, fortune-multiplier: 1.0,  auto-smelt: false, radius: 0 }
    3: { name: "<yellow>Iron",   item: IRON_PICKAXE,      cost: 1000, efficiency: 3, haste: 1, fortune-multiplier: 1.25, auto-smelt: true,  radius: 0 }
    4: { name: "<aqua>Diamond",  item: DIAMOND_PICKAXE,   cost: 2500, efficiency: 5, haste: 2, fortune-multiplier: 1.5,  auto-smelt: true,  radius: 1 }
    5: { name: "<light_purple>Netherite", item: NETHERITE_PICKAXE, cost: 5000, efficiency: 5, haste: 3, fortune-multiplier: 2.0, auto-smelt: true, radius: 1 }
Tune the pace

With the defaults, a player needs 10000 credits. Raise ore values or lower unban-threshold for a shorter stay, and do the reverse for a longer one. Players can check progress in the sidebar and boss bar.

#Credits, economy and the webstore

Where credits are kept

economy.provider chooses the balance that counts toward release:

  • internal: mcBans' own counter, separate from your economy. This is the default and needs no other plugin.
  • vault: the player's Vault economy balance.
  • playerpoints: the player's PlayerPoints balance.
  • coinsengine: a CoinsEngine currency, named by economy.coinsengine-currency.

With an external provider, the threshold is taken from the balance on release, and pickaxe upgrades are paid from the same balance.

economy:
  provider: internal
  coinsengine-currency: "coins"

Admin commands

All need mcbans.purgatory.admin and work on offline players:

  • /purgatory give <player> <credits> and /purgatory take <player> <credits>.
  • /purgatory setpickaxe <player> <tier> sets their pickaxe tier.
  • /purgatory status <player> shows credits, lifetime credits, ore mined, tier and the active purgatory ban.
  • /purgatory reset <player> resets their purgatory progress.

Selling credits

Players open the credit store from the pickaxe menu (right-click the pickaxe, then Buy credits) or with /purgatory store. Clicking a package sends a clickable link to your webstore. mcBans does not take payments itself.

store:
  enabled: true
  url: "https://store.example.com"
  packages:
    pouch:
      name: "<white>Pickaxe Pouch"
      credits: 1000
      price: "$2.99"
      icon: GOLD_NUGGET
      url: ""            # empty = the main store url above

In your webstore (Tebex or similar), make each package run this console command after purchase:

purgatory give {username} 5000

It works while the player is offline or on another server. The player must have joined at least once, or use their UUID instead of the name. If the new balance reaches purgatory.unban-threshold, they are released right away.

Match the package credits

The credits shown in game come from store.packages, but the credits actually given come from your webstore command. Keep the two in sync.

#Control panel

/modpanel [player] (aliases /mp, /punishgui) opens the panel. With a player name it opens that player's record directly. Live counts of bans, purgatory, mutes, frozen players, warnings and total records load a moment after it opens.

  • Find player: search any player, online or offline. See their full history, accounts that share their IP, and purgatory credits, with a button for every action. Punish buttons use the length and reason presets from gui.duration-presets and gui.reason-presets, and you can type your own in chat.
  • Online players, Active punishments (filterable by type) and Recent activity, a feed of every record.
  • Staff activity: what each staff member issued and reversed.
  • Purgatory: who is inside, refill, rebuild and spawn. Needs mcbans.purgatory.admin.
  • Settings: edits config.yml in game. Needs mcbans.admin.

Buttons check permissions, so a staff member without, for example, mcbans.ban cannot ban from the panel.

#Settings editor

Open /modpanel then Settings. Every option in config.yml has a button: punishments and broadcasts, warn rules, freeze, purgatory, ores, pickaxe tiers, credit packages, storage and network. Changes are saved to config.yml with its comments kept, and apply at once, except the few options marked "needs a restart" in their button.

Secrets

Some values, such as the MySQL password, are treated as secret and are not shown in the menu text.

#Broadcasts and messages

Every action is announced in chat. broadcast.scope: staff (default) shows broadcasts only to players with mcbans.notify. all shows them to everyone, except silent (-s) actions, which stay staff-only. On a network, broadcast.network-wide: true shows them on every server.

All messages are in lang.yml as MiniMessage. Legacy & and &#RRGGBB codes also work. A list value is shown as several lines, and an empty value sends nothing. Reload with /mcbans reload.

These tags can be used in punishment messages and ban screens:

TagValue
<id>Record id
<type>Ban, Mute, Warning, Kick or Freeze
<player>, <staff>Target and issuer
<reason>The reason
<duration>, <remaining>Total length and time left
<date>, <expires>When it was issued and when it ends
<server>The server-name it was issued on
<ip>, <purgatory>Tags shown when the record is IP-based or a purgatory ban
<status>Active, Expired, Reversed or Issued
<removed_by>, <removed_reason>, <removed_date>Details of how it was ended
<appeal>The appeal line, or nothing if the appeal link is empty
<threshold>Credits needed to leave purgatory

#TAB plugin support

The TAB plugin sends its own tab list header and footer and would overwrite mcBans'. When TAB is installed, mcBans sets the header and footer of purgatory players through TAB, and hands them back to TAB when the player is released. You do not need to configure anything.

The console prints one of these lines at startup: "Hooked TAB: purgatory tab lists are set through TAB.", or a note that TAB's header/footer feature is off, or a warning that the hook failed. In the last two cases mcBans uses the normal tab list, which TAB may overwrite.

#Network setup (Velocity and BungeeCord)

On a network, purgatory is its own backend server. The proxy sends purgatory-banned players there, blocks them from every other server, and refuses hard-banned players at login. All servers and the proxy share one MySQL database.

  1. Create a MySQL or MariaDB database.
  2. On every backend, set storage.type: MYSQL with the same database and credentials, a different server-name for each server, and network.purgatory-server to the purgatory backend's name in your proxy.
  3. On the purgatory backend only, set network.this-is-purgatory-server: true. It then hosts the purgatory world.
  4. Put the same jar on the proxy and start it once. Then edit plugins/mcbans/config.yml on Velocity or plugins/mcBans/config.yml on BungeeCord: the MySQL details, purgatory.server and purgatory.release-server.
  5. Restart everything and run /mcbans info on a backend to confirm the mode.
network:
  mode: auto
  purgatory-server: "purgatory"
  this-is-purgatory-server: false
  route-timeout-seconds: 8

network.mode is auto (proxy mode when the backend is behind a proxy and a purgatory server is set), single or proxy. route-timeout-seconds is how long a purgatory-banned player may stay on a backend before being disconnected, if the proxy did not move them.

Proxy config

mysql:
  host: "localhost"
  port: 3306
  database: "mcbans"
  username: "root"
  password: ""
  ssl: false
  pool-size: 4
  # Must match storage.table-prefix on the backends.
  table-prefix: "mcbans_"

purgatory:
  # Must match purgatory.enabled on the backends.
  enabled: true
  # The purgatory backend's name in the proxy's server list.
  server: "purgatory"
  # Where players go when they are released from purgatory.
  release-server: "lobby"

The proxy messages (messages.ban-screen, purgatory-unavailable, sent-to-purgatory, released) use & color codes. The ban screen supports {reason}, {staff}, {duration}, {expires}, {id}, {date} and {appeal}. Restart the proxy after changing this file.

MySQL is required

A network needs storage.type: MYSQL on every server and on the proxy, with the same table-prefix. YAML and SQLite only work on a single server.

#Update checker

Copies downloaded from BuiltByBit check for new versions on startup and every 24 hours. The console and online players with mcbans.admin are told when one is available, and admins are reminded when they join.

updates:
  enabled: true
  check-on-startup: true
  check-interval-hours: 24
  auto-download: false
  notify: true
  shared-token: ""
  resource-id: 0
  • With auto-download: true, the new jar is downloaded into plugins/update and installed on the next restart. The old jar is saved in plugins/mcBans/backup. The download is checked to be mcBans at the expected version first.
  • Downloading needs a BuiltByBit license for the resource. Without usage rights you only get a notice.
  • Leave shared-token and resource-id blank unless support tells you otherwise.
  • Copies that did not come from BuiltByBit log "Update checks are off" and do nothing.

#Commands

Optional arguments are in square brackets. Lengths like 2h30m or permanent are explained in Bans, mutes, warnings and kicks. Every command has tab completion.

CommandWhat it doesPermission
/ban <player> [length] [-s] [-ip] [-p|-np] [reason]Ban a player. Permanent unless a length is given. Goes to purgatory by default.mcbans.ban
/tempban <player> <length> [flags] [reason]Ban a player for a length of time.mcbans.tempban
/unban <player> [-s] [reason]Lift a ban and release from purgatory. Alias: /pardon.mcbans.unban
/mute <player> [length] [-s] [-ip] [reason]Mute a player. Permanent unless a length is given.mcbans.mute
/tempmute <player> <length> [-s] [-ip] [reason]Mute a player for a length of time.mcbans.tempmute
/unmute <player> [-s] [reason]Lift a mute.mcbans.unmute
/warn <player> [-s] [reason]Warn a player. May trigger an escalation rule.mcbans.warn
/unwarn <player> [id] [-s] [reason]Remove one warning by id, or the newest active one.mcbans.unwarn
/kick <player> [-s] [reason]Kick an online player.mcbans.kick
/freeze <player> [length] [-s] [reason]Freeze an online player. Run it again on a frozen player to open the staff tools. Alias: /ss.mcbans.freeze
/unfreeze <player> [-s] [reason]Unfreeze a player.mcbans.unfreeze
/history <player> [page]Show a player's punishment history in chat. Aliases: /hist, /punishments.mcbans.history
/modpanel [player]Open the control panel, or a player's record. Aliases: /mp, /punishgui.mcbans.modpanel
/purgatory give <player> <credits>Give purgatory credits. Works from the console and on offline players. Alias: /purg.mcbans.purgatory.admin
/purgatory take <player> <credits>Take purgatory credits.mcbans.purgatory.admin
/purgatory setpickaxe <player> <tier>Set a player's pickaxe tier.mcbans.purgatory.admin
/purgatory status <player>Show a player's credits, lifetime credits, ore mined, tier and purgatory ban.mcbans.purgatory.admin
/purgatory reset <player>Reset a player's purgatory progress.mcbans.purgatory.admin
/purgatory tpTeleport to the purgatory spawn (on the server that hosts purgatory).mcbans.purgatory.setup
/purgatory setspawnSet the purgatory spawn to where you stand.mcbans.purgatory.setup
/purgatory setmine pos1|pos2Mark your own mine area with two corners.mcbans.purgatory.setup
/purgatory refillRefill every ore block in the mine now.mcbans.purgatory.setup
/purgatory rebuildBuild the Hollow again.mcbans.purgatory.setup
/purgatory upgradeOpen the pickaxe upgrade menu (players in purgatory).mcbans.purgatory.self
/purgatory storeOpen the credit store menu.mcbans.purgatory.self
/mcbans infoShow version, storage, network mode, purgatory location and credit bank.mcbans.info
/mcbans reloadReload config.yml and lang.yml. Storage and network settings need a restart.mcbans.admin
/mcbans edit <id> reason <text>Change the reason of a record.mcbans.edit
/mcbans edit <id> duration <length>Change the length of a record.mcbans.edit
/mcbans expire <id> [reason]End a record now. It stays in the history as Expired.mcbans.edit
/mcbans reverse <id> [reason]Pardon a record. It stays in the history as Reversed.mcbans.edit

#Permissions

mcbans.staff gives all moderation permissions. mcbans.* gives everything.

PermissionWhat it allowsDefault
mcbans.*Everything in mcBans. Includes mcbans.staff, mcbans.admin, the purgatory admin, setup, bypass and build permissions, and mcbans.exempt.op
mcbans.staffAll moderation commands and the panel: ban, tempban, unban, mute, tempmute, unmute, warn, unwarn, kick, freeze, unfreeze, freeze.inventory, history, modpanel, edit, ip, notify, info, purgatory.see and purgatory.spy. Does not include mcbans.admin.op
mcbans.banUse /ban.op
mcbans.tempbanUse /tempban.op
mcbans.unbanUse /unban.op
mcbans.muteUse /mute.op
mcbans.tempmuteUse /tempmute.op
mcbans.unmuteUse /unmute.op
mcbans.warnUse /warn.op
mcbans.unwarnUse /unwarn.op
mcbans.kickUse /kick.op
mcbans.freezeUse /freeze and the freeze panel.op
mcbans.unfreezeUse /unfreeze.op
mcbans.freeze.inventoryView a frozen player's inventory from the freeze panel.op
mcbans.historyUse /history.op
mcbans.modpanelOpen /modpanel.op
mcbans.editEdit, end early or reverse any record (/mcbans edit, expire, reverse and the GUI).op
mcbans.ipUse -ip to also punish the IP address.op
mcbans.notifySee punishment broadcasts.op
mcbans.infoUse /mcbans info.op
mcbans.adminUse /mcbans reload, open the Settings editor and receive update notices.op
mcbans.exemptCannot be banned, muted, kicked or frozen by other staff while online.false (nobody, not even ops)
mcbans.purgatory.selfPlayers in purgatory can use /purgatory upgrade and /purgatory store.true (everyone)
mcbans.purgatory.adminGive or take credits, set pickaxe tiers, view and reset progress, and open the purgatory part of the panel.op
mcbans.purgatory.setupSet the purgatory spawn and mine, refill, rebuild and teleport there.op
mcbans.purgatory.seeSee players who are in purgatory.op
mcbans.purgatory.spyRead purgatory chat.op
mcbans.purgatory.bypassIgnore the purgatory command allow-list.op
mcbans.purgatory.buildBreak and place blocks in the purgatory world (as someone who is not serving a purgatory ban).op

#Placeholders and message tags

mcBans does not register PlaceholderAPI placeholders. It uses MiniMessage tags inside lang.yml. The punishment tags are listed in Broadcasts and messages. These tags are available in purgatory messages, the sidebar and the GUI:

PlaceholderValue
<credits>The player's current purgatory credits.
<threshold>Credits needed to be released.
<lifetime>Credits earned over all purgatory stints (in /purgatory status).
<ore>Ore blocks mined (in /purgatory status).
<tier>, <max_tier>Pickaxe tier and the highest tier (in /purgatory status).
<gained>, <blocks>Credits gained and blocks mined, in the +credits message while mining.
<prefix>The mcBans chat prefix from lang.yml.

#Configuration reference

The most important config.yml options. Run /mcbans reload after editing. Options marked as storage or network need a restart. Most of them can also be changed in game from /modpanel, Settings.

SettingDefaultWhat it does
server-namesurvivalThis server's name, saved on every record. Use a different name per server on a network.
storage.typeSQLITEYAML (files in plugins/mcBans/data), SQLITE (plugins/mcBans/mcbans.db) or MYSQL. MYSQL is required on a network.
storage.table-prefixmcbans_Prefix of the database tables. Must match on the proxy.
storage.mysql.*localhost:3306, db mcbanshost, port, database, username, password, ssl and pool-size for MySQL or MariaDB.
storage.deny-login-on-errortrueIf the database cannot be reached when someone joins, refuse the join instead of letting them in unchecked.
network.modeautoauto, single or proxy.
network.purgatory-serverpurgatoryProxy mode: the purgatory server name in the proxy list.
network.this-is-purgatory-serverfalseSet to true only on the backend that hosts purgatory.
network.route-timeout-seconds8Seconds before a purgatory-banned player still on a backend is disconnected.
broadcast.scopestaffstaff or all.
broadcast.network-widetrueShow broadcasts on every server of the network.
punishments.appealhttps://example.com/appealAppeal link used as the appeal tag. Empty hides the line.
punishments.ip-by-defaultfalseBan and mute the IP as well by default.
punishments.default-reasonsper typeReason used when staff give none, for ban, mute, warn, kick and freeze.
punishments.muted-blocked-commandsmsg, tell, w, ...Commands muted players cannot use.
warns.expire-after30dHow long a warning counts. permanent = never.
warns.thresholds3, 5, 7Automatic punishments by warning count.
freeze.*see Freezeindicator (title, bossbar, bossbar-color, actionbar), block-damage, allowed-commands, chat-log-size and quit-punishment.
purgatory.enabledtrueOff makes every ban a normal ban.
purgatory.default-for-banstrueBans go to purgatory unless -np is used.
purgatory.unban-threshold10000Credits needed to be released.
purgatory.reset-on-new-bantrueA new purgatory ban starts at 0 credits and tier 1.
purgatory.worldmcbans_purgatoryWorld name for purgatory.
purgatory.mine.auto-buildtrueBuild the Hollow on first start.
purgatory.mine.regen-seconds30Seconds until a mined block grows back as ore.
purgatory.save-inventorytrueSingle server: keep the inventory while in purgatory and return it on release.
purgatory.release-locationspawnspawn or last.
purgatory.chatpurgatorynone, purgatory or staff.
purgatory.hide-otherstrueHide purgatory players from everyone else and the other way around.
purgatory.bossbar / scoreboard / no-damagetrueProgress boss bar, sidebar scoreboard, and no damage, hunger or death.
purgatory.allowed-commandspurgatory, msg, r, ...The only commands purgatory players may use.
purgatory.ores7 oresvalue, smelt-value and weight for each ore.
purgatory.pickaxe.tiers5 tiersname, item, cost, efficiency, haste, fortune-multiplier, auto-smelt and radius per tier.
store.enabled / urltrue / https://store.example.comCredit store switch and the main store link.
store.packages3 packagesname, credits, price, icon and an optional url for each package.
economy.providerinternalinternal, vault, playerpoints or coinsengine.
economy.coinsengine-currencycoinsThe CoinsEngine currency to use.
gui.duration-presets30m ... permanentUp to 8 length buttons in the punish screen.
gui.reason-presetsHacking, X-ray, ...Up to 8 reason buttons in the punish screen. Also offered in tab completion.
updates.*enabledenabled, check-on-startup, check-interval-hours, auto-download, notify, shared-token and resource-id.

#Files and data

FilePurpose
plugins/mcBans/config.ymlStorage, network, broadcasts, warnings, freeze, purgatory, store, economy, GUI presets, updates. Commented.
plugins/mcBans/lang.ymlEvery message, ban screen, broadcast, GUI title and item text. MiniMessage, with & codes also supported.
plugins/mcBans/purgatory-world.ymlThe mine area and spawn, set in game.
plugins/mcBans/mcbans.dbSQLite database (default storage).
plugins/mcBans/data/YAML storage files, if you use storage.type: YAML.
plugins/mcBans/backup/The previous jar, saved when an update is downloaded.
Proxy config.ymlMySQL, purgatory and release server names and the ban screen (Velocity: plugins/mcbans, BungeeCord: plugins/mcBans).

#Troubleshooting and FAQ

A banned player was not sent to purgatory and got a normal ban screen.

Check that purgatory.enabled is true, that the ban was not given with -np, and that purgatory.default-for-bans is on (or use -p). Run /mcbans info to see where purgatory lives. On a network, make sure network.purgatory-server matches the proxy server name and purgatory.server matches in the proxy config.

/purgatory setspawn, setmine, refill or rebuild says purgatory is not hosted here.

These only work on the server that hosts the purgatory world. On a single server that is the server itself. On a network, run them on the backend that has network.this-is-purgatory-server: true. For setspawn and setmine you must also stand in the purgatory world, which /purgatory tp takes you to.

My staff cannot open Settings or run /mcbans reload.

Those need mcbans.admin, which is not part of mcbans.staff. The purgatory section of the panel needs mcbans.purgatory.admin.

A staff member says "no permission" for -ip.

The -ip flag needs mcbans.ip. It is part of mcbans.staff.

I cannot ban, mute, kick or freeze another staff member.

Players with mcbans.exempt are protected from other staff while online. It defaults to false, so check your permission plugin for a wildcard that includes it. You can still warn them.

Webstore credits did not arrive.

The command must be run from the console as purgatory give {username} <credits>. The player has to have joined the server at least once, or you can use their UUID. Test the same command by hand in the console. The player does not have to be online.

Purgatory players see the normal TAB header or footer.

TAB overwrites anything sent directly. Install TAB and check the startup log for "Hooked TAB". If TAB's header/footer feature is disabled, mcBans falls back to the normal tab list, and TAB may overwrite it.

Players cannot join and see "Your record could not be loaded".

The database could not be reached. Check your MySQL details and that the database is running. If you would rather let players in unchecked while the database is down, set storage.deny-login-on-error: false, but banned players could then join.

Can I use SQLite or YAML on a network?

No. SQLite and YAML are for a single server. A network needs one MySQL or MariaDB database that every backend and the proxy use.

The update checker does nothing.

Update checks only run in copies downloaded from BuiltByBit and when updates.enabled is true. Auto-download also needs updates.auto-download: true and a license for the resource. The new jar is installed on the next restart.

A warning did not trigger a punishment.

Thresholds match the exact number of active warnings. Expired or removed warnings do not count (warns.expire-after is 30 days by default), and the 4th warning does nothing with the default rules.

A player says the ore does not break in purgatory.

They must use the purgatory pickaxe, and the block must be an ore from purgatory.ores inside the mine area. A mined block turns into bedrock until it regrows. If you set your own mine with /purgatory setmine, check that the area covers the ores.

How do I give a player their stuff back or end a stint early?

Use /unban <player>. It releases them from purgatory, and on a single server their saved inventory is returned. To reduce a stay without unbanning, give credits with /purgatory give.

#Updating

  1. Stop the server and replace the old jar in plugins/ with the new one. On a network, do the same on the proxy.
  2. Start the server. Existing config.yml and lang.yml are kept, and settings missing from an older file use their defaults. Check CHANGELOG or the resource page for new options and copy them into your file if you want to change them.
  3. Or turn on updates.auto-download and restart. The new jar is installed from plugins/update and the old one is kept in plugins/mcBans/backup.
Back up first

Copy plugins/mcBans (or your MySQL database) before a major update, so you can roll back if needed.

Version 1.0.1

  • New: BuiltByBit update checker.
  • New: the Hollow cave mine, a purgatory sidebar scoreboard, a framed GUI, clickable credit store links and TAB plugin support.
  • Fixed: list menus placed items in the border, and the /purgatory rebuild message now confirms when it finishes.