Content generated with AI — it may contain mistakes.

ExyliaStaff/GuidesUpdated in v1.8.0

Punish players

Set up categories, reasons and an escalation ladder, enforced by the plugin or by your ban plugin, with approvals and history.

Page 14 of 3811 min read

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. Add exyliastaff.punish.history for /history. To stop a rank from using harsh steps, see Approvals.
  • The module switch is modules.punishments in plugins/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: exylia enforces 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.

Only what this plugin issued counts

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.

EngineWho enforcesWhat it needs
commandsYour ban plugin, through the template of the step's type in commands.A ban plugin, or vanilla.
exyliaThis 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 the screen-ban screen. 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 in mute-blocked-commands, answered with the muted lines.
  • Warnings show the warned lines 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#

CommandWhat it doesPermission
/punish <player> [reason]Open the punishment screen for a player, or apply a configured reason by its id.exyliastaff.punish
/punish requestsList 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
PermissionWho has itWhat it allows
exyliastaff.punishAdmins (op)Punish players.
exyliastaff.punish.historyAdmins (op)Read a player's punishment history.
exyliastaff.punish.permanentEveryoneIssue a punishment that never expires. Set to false to send them for approval.
exyliastaff.punish.editEveryoneEdit a punishment from the web. Set to false to send edits for approval.
exyliastaff.punish.revokeEveryoneRevoke a punishment from the web. Set to false to send revokes for approval.
Configuration and messages
plugins/ExyliaStaff/modules/punishments/config.yml
yaml
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
KeyDefaultWhat it does
categories.<id>.reasons.<id>see aboveA reason: name, description lines, icon and its ladder. Reason ids must be unique across categories; menus list them in file order.
commandssee aboveTemplate per step type for engine: commands. %reason% is the reason's display name, not its id.
revoke-commandssee aboveHow a punishment revoked from Exylia Staff Web is undone, per type. KICK and WARN have none.
ladder-reset-days30Older punishments no longer advance the ladder. 0 counts everything.
require-confirmationtrueShow the confirm screen.
broadcast.enabled, broadcast.to-staff-onlytrue, trueAnnounce punishments, and to whom (false announces to everyone).
enginecommandscommands runs the templates; exylia enforces natively.
appeal-urlautoThe appeal link, %id% being the punishment. auto from the linked web, empty for none.
mute-blocked-commandsmsg, tell, w, whisper, r, reply, me, say, mailCommands a muted player may not run, without the slash, matched on the bare label (minecraft:msg counts as msg). Only with engine: exylia.
evidence-lines1Last chat lines kept when the web attached none. 0 to 20.
observetrueRecord what LiteBans, LibertyBans, AdvancedBan and BanManager do.
ip-ban-hold-days14Days 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.

PlaceholderShowsExample
%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