Punish players
Set up categories, reasons and an escalation ladder, enforced by the plugin or by your ban plugin, with approvals and history.
Punishments in ExyliaStaff are a menu of reasons, each with a ladder: first offence, second offence, and so on. A staff member picks a reason, and the plugin counts how often that player was punished for it before and applies the matching step. You choose who enforces it: the plugin itself, or your ban plugin.
Before you start#
- Give staff
exyliastaff.punish. Addexyliastaff.punish.historyfor/history. To stop a rank from using harsh steps, see Approvals. - The module switch is
modules.punishmentsinplugins/ExyliaStaff/config.yml. - Decide the engine in
modules/punishments/config.yml:engine: commands(the default) runs your ban plugin's commands (LiteBans, AdvancedBan, vanilla);engine: exyliaenforces everything natively and needs no other plugin. See Engines.
Steps#
Open the menu
Run /punish <player>, or click the netherite axe PUNISH (it targets the player you look at) in the staff mode hotbar. The player may be offline if the server has seen them. A player cannot punish themself.
Pick a category and a reason
Categories first (Cheating, Chat, Griefing, Other by default), then reasons. Each reason shows its ladder with the steps already used, the current one marked, and the step that will be applied now. The last line says whether a click punishes at once or sends the step for approval.
Confirm
With require-confirmation on (the default) a confirm screen opens: click Confirm, or Cancel to go back to the reasons. With it off, the click executes.
To skip the menu, run /punish <player> <reason-id> (for example /punish Steve hacks): it executes at once, with no confirm screen.
Check that it works#
Punish a test account with a ladder's first step (for example Spam, first step MUTE 1h). The issuer is told, staff with exyliastaff.punish get an announcement on every server, and /history <player> (alias /phistory) lists it, newest first.
Going further#
The ladder#
A ladder line is TYPE duration, or just TYPE. The types are BAN, TEMPBAN, MUTE, TEMPMUTE, KICK, WARN and IPBAN; a duration is 1h, 7d, 1h30m or perm. The step is the number of earlier punishments of that player with the same reason id within ladder-reset-days (default 30): the first offence uses the first line, and when the ladder runs out the last step repeats. Different reasons do not advance each other, and ladder-reset-days: 0 counts everything ever.
The history is the plugin's own. With observe on, a ban typed straight into LiteBans is recorded too, but under the ban plugin's name as its reason (litebans), so it is not a step on any ladder. Punish through the menu and the ladder is always right.
Engines#
engine decides who enforces a step.
| Engine | Who enforces | What it needs |
|---|---|---|
commands | Your ban plugin, through the template of the step's type in commands. | A ban plugin, or vanilla. |
exylia | This plugin: the stored row is the punishment. | Nothing else. Redis and ExyliaProxyUtils refuse bans at the proxy. |
Execution through commands. With engine: commands, the template for the step's type runs with %player%, %duration%, %reason% and %staff%. The duration is passed as written in the ladder, 7d or 1h30m, so write it the way your ban plugin reads it; a bare type passes perm. console: runs here, console-proxy: on the proxy through the library's bridge. A step type with no template is refused with "no command for TEMPBAN" and nothing is recorded.
The native engine. With engine: exylia, commands and revoke-commands are not used.
- Bans (
BAN,TEMPBAN,IPBAN) are refused at login on every backend, from the database, with thescreen-banscreen. Each active ban is also mirrored to Redis so ExyliaProxyUtils refuses it at the proxy before a backend is reached; the mirror is rewritten on every start and reload. If the database cannot be read at login, the player is let in rather than locking everybody out. - Kicks show
screen-kick. A player on another server is kicked through the proxy. - Mutes (
MUTE,TEMPMUTE) cancel every chat line and every command inmute-blocked-commands, answered with themutedlines. - Warnings show the
warnedlines at once, or at the player's next join on any server, and only once.
A ban or mute lifted or edited from Exylia Staff Web reaches the player's server and the mirror straight away. Either engine records the row, tells the issuer and publishes the punishment: every server announces it to staff with exyliastaff.punish, or to everyone when broadcast.to-staff-only is off.
IP bans#
An IPBAN step with engine: exylia bans the addresses the banned player was seen on, but not blindly, because a home address gets reassigned and a mobile address is shared by strangers.
- Each address is held for
ip-ban-hold-days(default 14) after the banned player last used it, or for as long as they had used it if that is longer. A fixed home line stays held; a dynamic address is let go after it moves on. A value of 0 behaves like 1 day. - Wherever the banned player tries to log in from is held from then on. An IP ban issued while they were offline learns the address at their next login attempt.
- On a held address, only accounts that look like theirs are refused: accounts created since the ban, and accounts that used that address before it. Established players the ISP handed the address to are let in, and so is every account on a crowded address (mobile, CGNAT, public wifi).
- Local addresses (the proxy, a LAN, loopback) are never held. The proxy mirror carries account bans only, so IP bans are enforced by the backend at login.
Evidence and appeals#
Every punishment keeps the chat that led to it: the window the web sets or, when there was none, the target's last evidence-lines lines (default 1). The screens show it as %evidence%, with formatting the player typed stripped. appeal-url is the appeal link on the screens, %id% being the punishment: auto builds it from the linked web and shows nothing while the network is not linked; empty never shows one.
Approvals#
exyliastaff.punish lets a staff member punish. The punishment limit nodes narrow it per type, permanent steps, category and reason; each is allowed unless it is set to false. A step one of them blocks is not refused: it becomes a request.
The request
The staff member is told the step needs a superior's approval and gets its number. Every online staff member with exyliastaff.punish, on every server, for whom the same step is not blocked, gets request-alert with clickable approve and deny buttons. The web is told too. /punish requests lists the ten newest pending ones.
Approval
/punish approve <id>, or the button. The step is worked out again at that moment, so a ladder that moved meanwhile is respected, and applied with the approver as the staff member and Requested by <name> as its note. Nobody may resolve their own request, and an approver the step is blocked for is refused with the nodes that block it.
The answer
/punish deny <id> turns it down. The requester is told who approved or denied it, on whichever server they are.
The console is never blocked. A punishment from the web is checked against the staff member's LuckPerms nodes.
Observing other ban plugins#
With observe on (default), punishments made through LiteBans, LibertyBans, AdvancedBan or BanManager are recorded in the history, even a plain /ban that never touched this plugin, with their lifts. They are read on any backend where the ban plugin is installed and, with ExyliaProxyUtils, on the proxy. On a network every entry goes through one Redis stream read in the same group, so it is recorded once. With engine: commands, the ban plugin's own copy of a punishment this plugin just issued is linked to it rather than recorded twice. IP punishments that name no player are skipped.
Importing a ban plugin#
/staffadmin import <litebans|libertybans|advancedban|banmanager> (needs exyliastaff.admin) reads that plugin's whole history once: through its API when it is installed on this server, otherwise through the proxy's punish-import (see ExyliaProxyUtils). Rows arrive like observed ones and reach the web as they are read; it works with observe off. From LiteBans it reads bans, mutes, warnings and kicks. "is installed neither here nor on the proxy" means neither could run it.
To delete a player's history, or one reason's, run /staffadmin history clear <player> [reason-id] [confirm] (needs exyliastaff.admin.history.clear). An active ban is not lifted. See Commands.
Commands and permissions#
| Command | What it does | Permission |
|---|---|---|
/punish <player> [reason] | Open the punishment screen for a player, or apply a configured reason by its id. | exyliastaff.punish |
/punish requests | List the punishments waiting for approval. | exyliastaff.punish |
/punish approve <id> | Approve a pending punishment request. | exyliastaff.punish |
/punish deny <id> | Deny a pending punishment request. | exyliastaff.punish |
/history <player> | Open a player's punishment history. | exyliastaff.punish.history |
| Permission | Who has it | What it allows |
|---|---|---|
exyliastaff.punish | Admins (op) | Punish players. |
exyliastaff.punish.history | Admins (op) | Read a player's punishment history. |
exyliastaff.punish.permanent | Everyone | Issue a punishment that never expires. Set to false to send them for approval. |
exyliastaff.punish.edit | Everyone | Edit a punishment from the web. Set to false to send edits for approval. |
exyliastaff.punish.revoke | Everyone | Revoke a punishment from the web. Set to false to send revokes for approval. |
Configuration and messages
categories:
cheating:
name: Cheating
icon: DIAMOND_SWORD
reasons:
hacks:
name: Hacked client
description:
- Killaura, fly, speed or any unfair modification.
icon: DIAMOND_SWORD
ladder:
- TEMPBAN 7d
- BAN
xray:
name: X-Ray
description:
- Ore tracing or resource pack x-ray.
icon: DIAMOND_ORE
ladder:
- TEMPBAN 3d
- TEMPBAN 14d
- BAN
chat:
name: Chat
icon: WRITABLE_BOOK
reasons:
spam:
name: Spam
description:
- Flooding or repeating messages.
icon: PAPER
ladder:
- MUTE 1h
- TEMPMUTE 1d
- TEMPBAN 3d
toxicity:
name: Toxicity
description:
- Insults, harassment or hate speech.
icon: TNT
ladder:
- TEMPMUTE 6h
- TEMPMUTE 3d
- TEMPBAN 7d
- BAN
advertising:
name: Advertising
description:
- Promoting other servers or links.
icon: OAK_SIGN
ladder:
- TEMPMUTE 1d
- BAN
griefing:
name: Griefing
icon: TNT
reasons:
grief:
name: Griefing
description:
- Destroying or stealing from other players.
icon: TNT
ladder:
- WARN
- TEMPBAN 3d
- BAN
other:
name: Other
icon: BOOK
reasons:
staff-disrespect:
name: Staff disrespect
description:
- Ignoring or insulting staff.
icon: BARRIER
ladder:
- WARN
- KICK
- TEMPBAN 1d
commands:
BAN: 'console:ban %player% %reason%'
TEMPBAN: 'console:tempban %player% %duration% %reason%'
MUTE: 'console:mute %player% %reason%'
TEMPMUTE: 'console:tempmute %player% %duration% %reason%'
KICK: 'console:kick %player% %reason%'
WARN: 'console:warn %player% %reason%'
IPBAN: 'console:ipban %player% %reason%'
revoke-commands:
BAN: 'console:unban %player%'
TEMPBAN: 'console:unban %player%'
IPBAN: 'console:unbanip %player%'
MUTE: 'console:unmute %player%'
TEMPMUTE: 'console:unmute %player%'
ladder-reset-days: 30
require-confirmation: true
broadcast:
enabled: true
to-staff-only: true
engine: commands
appeal-url: auto
mute-blocked-commands:
- msg
- tell
- w
- whisper
- r
- reply
- me
- say
- mail
evidence-lines: 1
observe: true
ip-ban-hold-days: 14| Key | Default | What it does |
|---|---|---|
categories.<id>.reasons.<id> | see above | A reason: name, description lines, icon and its ladder. Reason ids must be unique across categories; menus list them in file order. |
commands | see above | Template per step type for engine: commands. %reason% is the reason's display name, not its id. |
revoke-commands | see above | How a punishment revoked from Exylia Staff Web is undone, per type. KICK and WARN have none. |
ladder-reset-days | 30 | Older punishments no longer advance the ladder. 0 counts everything. |
require-confirmation | true | Show the confirm screen. |
broadcast.enabled, broadcast.to-staff-only | true, true | Announce punishments, and to whom (false announces to everyone). |
engine | commands | commands runs the templates; exylia enforces natively. |
appeal-url | auto | The appeal link, %id% being the punishment. auto from the linked web, empty for none. |
mute-blocked-commands | msg, tell, w, whisper, r, reply, me, say, mail | Commands a muted player may not run, without the slash, matched on the bare label (minecraft:msg counts as msg). Only with engine: exylia. |
evidence-lines | 1 | Last chat lines kept when the web attached none. 0 to 20. |
observe | true | Record what LiteBans, LibertyBans, AdvancedBan and BanManager do. |
ip-ban-hold-days | 14 | Days an IP ban keeps holding an address after the banned player last used it. Only with engine: exylia. |
alert is a library effect played to staff on every announcement; it is empty by default.
Messages are in lang/<language>/modules/punishments/messages.yml: executed (%type%, %target%, %reason%); alert and broadcast (%staff%, %target%, %type%, %duration%, %server%, %reason%); never-played, unknown-reason, command-failed (%detail%), history-empty, self, no-target; the ladder lines ladder-current, ladder-step and ladder-done (%index%, %type%, %duration%); duration-permanent. Approvals: request-sent, request-alert, requests-header, requests-line, requests-empty, request-approved, request-denied, request-approved-notice, request-denied-notice, request-missing, request-own, request-blocked (%nodes%); the last line of a reason in the menu is reason-click or reason-click-approval. Native engine: screen-ban and screen-kick, muted and warned, all taking %reason%, %staff%, %date%, %expires%, %remaining%, %id%, %evidence%, %appeal% and %appeal_url%; evidence-line (%message%), evidence-none, appeal-line, expires-never. Import: import-usage, import-started, import-proxy, import-unsupported (%origin%). See ExyliaLib messages, menus and colours.
| Placeholder | Shows | Example |
|---|---|---|
%exyliastaff_staff_punishments_total% | Punishments you have issued. | 40 |
%exyliastaff_staff_punishments_today% | Of those, issued today. | 3 |
Something missing on this page? Tell us on Discord