#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.ymland every option is inconfig.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
- Put the jar in
plugins/. - Start the server. mcBans creates
config.ymlandlang.yml, uses SQLite by default, and builds the worldmcbans_purgatorywith a ready-made mine. - Give your staff
mcbans.staff(see Permissions).
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
- Set
server-nameinconfig.yml. It is saved on every record as the server it was issued on. - Set
punishments.appealto your appeal page. It appears on ban screens. Leave it empty to hide the line. - 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). - Run
/mcbans reloadafter editing files. Storage and network settings need a full restart. - Run
/mcbans infoto see the version, storage type, network mode, purgatory location and credit bank in use. - Run
/purgatory tpas an admin to look at the Hollow, the cave that was built for you.
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
| Flag | Meaning |
|---|---|
-s | Silent. Only staff with mcbans.notify see the broadcast. |
-ip | Also punish the player's IP address. Needs mcbans.ip. Applies to bans and mutes only. |
-p | Send the ban to purgatory (bans only). |
-np | Make 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-reasonsis 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.
/kickand/freezeneed the player to be online. Bans, mutes and warnings work on offline players too.- Players with
mcbans.exemptcannot 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: truetypeis BAN, MUTE, KICK or FREEZE.durationuses the same lengths as commands.purgatory: truesends a ban to purgatory.ip: truealso punishes the IP.<count>in the reason is replaced by the number of active warnings.- A warning stops counting after
warns.expire-after(usepermanentto 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.
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-damageis 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: falseThe 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
/bangoes to purgatory by default (purgatory.default-for-bans: true) unless you add-np. Use-pto force it when the default is off.- Warning escalation rules with
purgatory: true. - If
purgatory.enabledis 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) orstaff(only staff withmcbans.purgatory.spyread 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 withmcbans.purgatory.bypassignore 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 inlang.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: falseif 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 tpteleports you to the purgatory spawn./purgatory setspawnsets the spawn to where you stand (you must be in the purgatory world)./purgatory setmine pos1thenpos2marks your own ore area./purgatory refillrestores every ore block now./purgatory rebuildbuilds 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 }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 byeconomy.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 aboveIn your webstore (Tebex or similar), make each package run this console command after purchase:
purgatory give {username} 5000It 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.
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-presetsandgui.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.
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:
| Tag | Value |
|---|---|
<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.
- Create a MySQL or MariaDB database.
- On every backend, set
storage.type: MYSQLwith the same database and credentials, a differentserver-namefor each server, andnetwork.purgatory-serverto the purgatory backend's name in your proxy. - On the purgatory backend only, set
network.this-is-purgatory-server: true. It then hosts the purgatory world. - Put the same jar on the proxy and start it once. Then edit
plugins/mcbans/config.ymlon Velocity orplugins/mcBans/config.ymlon BungeeCord: the MySQL details,purgatory.serverandpurgatory.release-server. - Restart everything and run
/mcbans infoon a backend to confirm the mode.
network:
mode: auto
purgatory-server: "purgatory"
this-is-purgatory-server: false
route-timeout-seconds: 8network.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.
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 intoplugins/updateand installed on the next restart. The old jar is saved inplugins/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-tokenandresource-idblank 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.
| Command | What it does | Permission |
|---|---|---|
| /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 tp | Teleport to the purgatory spawn (on the server that hosts purgatory). | mcbans.purgatory.setup |
| /purgatory setspawn | Set the purgatory spawn to where you stand. | mcbans.purgatory.setup |
| /purgatory setmine pos1|pos2 | Mark your own mine area with two corners. | mcbans.purgatory.setup |
| /purgatory refill | Refill every ore block in the mine now. | mcbans.purgatory.setup |
| /purgatory rebuild | Build the Hollow again. | mcbans.purgatory.setup |
| /purgatory upgrade | Open the pickaxe upgrade menu (players in purgatory). | mcbans.purgatory.self |
| /purgatory store | Open the credit store menu. | mcbans.purgatory.self |
| /mcbans info | Show version, storage, network mode, purgatory location and credit bank. | mcbans.info |
| /mcbans reload | Reload 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.
| Permission | What it allows | Default |
|---|---|---|
| mcbans.* | Everything in mcBans. Includes mcbans.staff, mcbans.admin, the purgatory admin, setup, bypass and build permissions, and mcbans.exempt. | op |
| mcbans.staff | All 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.ban | Use /ban. | op |
| mcbans.tempban | Use /tempban. | op |
| mcbans.unban | Use /unban. | op |
| mcbans.mute | Use /mute. | op |
| mcbans.tempmute | Use /tempmute. | op |
| mcbans.unmute | Use /unmute. | op |
| mcbans.warn | Use /warn. | op |
| mcbans.unwarn | Use /unwarn. | op |
| mcbans.kick | Use /kick. | op |
| mcbans.freeze | Use /freeze and the freeze panel. | op |
| mcbans.unfreeze | Use /unfreeze. | op |
| mcbans.freeze.inventory | View a frozen player's inventory from the freeze panel. | op |
| mcbans.history | Use /history. | op |
| mcbans.modpanel | Open /modpanel. | op |
| mcbans.edit | Edit, end early or reverse any record (/mcbans edit, expire, reverse and the GUI). | op |
| mcbans.ip | Use -ip to also punish the IP address. | op |
| mcbans.notify | See punishment broadcasts. | op |
| mcbans.info | Use /mcbans info. | op |
| mcbans.admin | Use /mcbans reload, open the Settings editor and receive update notices. | op |
| mcbans.exempt | Cannot be banned, muted, kicked or frozen by other staff while online. | false (nobody, not even ops) |
| mcbans.purgatory.self | Players in purgatory can use /purgatory upgrade and /purgatory store. | true (everyone) |
| mcbans.purgatory.admin | Give or take credits, set pickaxe tiers, view and reset progress, and open the purgatory part of the panel. | op |
| mcbans.purgatory.setup | Set the purgatory spawn and mine, refill, rebuild and teleport there. | op |
| mcbans.purgatory.see | See players who are in purgatory. | op |
| mcbans.purgatory.spy | Read purgatory chat. | op |
| mcbans.purgatory.bypass | Ignore the purgatory command allow-list. | op |
| mcbans.purgatory.build | Break 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:
| Placeholder | Value |
|---|---|
| <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.
| Setting | Default | What it does |
|---|---|---|
| server-name | survival | This server's name, saved on every record. Use a different name per server on a network. |
| storage.type | SQLITE | YAML (files in plugins/mcBans/data), SQLITE (plugins/mcBans/mcbans.db) or MYSQL. MYSQL is required on a network. |
| storage.table-prefix | mcbans_ | Prefix of the database tables. Must match on the proxy. |
| storage.mysql.* | localhost:3306, db mcbans | host, port, database, username, password, ssl and pool-size for MySQL or MariaDB. |
| storage.deny-login-on-error | true | If the database cannot be reached when someone joins, refuse the join instead of letting them in unchecked. |
| network.mode | auto | auto, single or proxy. |
| network.purgatory-server | purgatory | Proxy mode: the purgatory server name in the proxy list. |
| network.this-is-purgatory-server | false | Set to true only on the backend that hosts purgatory. |
| network.route-timeout-seconds | 8 | Seconds before a purgatory-banned player still on a backend is disconnected. |
| broadcast.scope | staff | staff or all. |
| broadcast.network-wide | true | Show broadcasts on every server of the network. |
| punishments.appeal | https://example.com/appeal | Appeal link used as the appeal tag. Empty hides the line. |
| punishments.ip-by-default | false | Ban and mute the IP as well by default. |
| punishments.default-reasons | per type | Reason used when staff give none, for ban, mute, warn, kick and freeze. |
| punishments.muted-blocked-commands | msg, tell, w, ... | Commands muted players cannot use. |
| warns.expire-after | 30d | How long a warning counts. permanent = never. |
| warns.thresholds | 3, 5, 7 | Automatic punishments by warning count. |
| freeze.* | see Freeze | indicator (title, bossbar, bossbar-color, actionbar), block-damage, allowed-commands, chat-log-size and quit-punishment. |
| purgatory.enabled | true | Off makes every ban a normal ban. |
| purgatory.default-for-bans | true | Bans go to purgatory unless -np is used. |
| purgatory.unban-threshold | 10000 | Credits needed to be released. |
| purgatory.reset-on-new-ban | true | A new purgatory ban starts at 0 credits and tier 1. |
| purgatory.world | mcbans_purgatory | World name for purgatory. |
| purgatory.mine.auto-build | true | Build the Hollow on first start. |
| purgatory.mine.regen-seconds | 30 | Seconds until a mined block grows back as ore. |
| purgatory.save-inventory | true | Single server: keep the inventory while in purgatory and return it on release. |
| purgatory.release-location | spawn | spawn or last. |
| purgatory.chat | purgatory | none, purgatory or staff. |
| purgatory.hide-others | true | Hide purgatory players from everyone else and the other way around. |
| purgatory.bossbar / scoreboard / no-damage | true | Progress boss bar, sidebar scoreboard, and no damage, hunger or death. |
| purgatory.allowed-commands | purgatory, msg, r, ... | The only commands purgatory players may use. |
| purgatory.ores | 7 ores | value, smelt-value and weight for each ore. |
| purgatory.pickaxe.tiers | 5 tiers | name, item, cost, efficiency, haste, fortune-multiplier, auto-smelt and radius per tier. |
| store.enabled / url | true / https://store.example.com | Credit store switch and the main store link. |
| store.packages | 3 packages | name, credits, price, icon and an optional url for each package. |
| economy.provider | internal | internal, vault, playerpoints or coinsengine. |
| economy.coinsengine-currency | coins | The CoinsEngine currency to use. |
| gui.duration-presets | 30m ... permanent | Up to 8 length buttons in the punish screen. |
| gui.reason-presets | Hacking, X-ray, ... | Up to 8 reason buttons in the punish screen. Also offered in tab completion. |
| updates.* | enabled | enabled, check-on-startup, check-interval-hours, auto-download, notify, shared-token and resource-id. |
#Files and data
| File | Purpose |
|---|---|
plugins/mcBans/config.yml | Storage, network, broadcasts, warnings, freeze, purgatory, store, economy, GUI presets, updates. Commented. |
plugins/mcBans/lang.yml | Every message, ban screen, broadcast, GUI title and item text. MiniMessage, with & codes also supported. |
plugins/mcBans/purgatory-world.yml | The mine area and spawn, set in game. |
plugins/mcBans/mcbans.db | SQLite 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.yml | MySQL, 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
- Stop the server and replace the old jar in
plugins/with the new one. On a network, do the same on the proxy. - Start the server. Existing
config.ymlandlang.ymlare kept, and settings missing from an older file use their defaults. CheckCHANGELOGor the resource page for new options and copy them into your file if you want to change them. - Or turn on
updates.auto-downloadand restart. The new jar is installed fromplugins/updateand the old one is kept inplugins/mcBans/backup.
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 rebuildmessage now confirms when it finishes.