Modules

Punishments

Categories, reasons and an escalation ladder, executed through your ban plugin's commands, with a history per player.

The punishments module does not ban anyone itself. It holds the reasons and, for each one, a ladder: first offence, second offence, and so on. When a staff member picks a reason, the module counts how many times that player was punished for it before, takes the matching step, and runs the command you configured for that step's type. LiteBans, AdvancedBan or anything else with a /ban answers.

Module id punishments, switch modules.punishments, files under modules/punishments/.

Commands

Command	Permission	What it does
`/punish <player>`	`exyliastaff.punish`	Opens the categories menu. The player may be offline if the server has seen them.
`/punish <player> <reason-id>`	`exyliastaff.punish`	Executes at once, with no confirm screen.
`/history <player>`	`exyliastaff.punish.history`	Their punishments, newest first. `/phistory` is an alias.

The netherite axe in the hotbar opens the menu on the player you look at. A player cannot punish themself.

Categories, then reasons. Each reason shows its ladder with the steps already used, the current one marked, and the step that will be applied now. Clicking it opens a confirm screen when require-confirmation is on, otherwise executes. Cancel goes back to the reasons.

The ladder

A ladder line is TYPE duration, or just TYPE, with the types BAN, TEMPBAN, MUTE, TEMPMUTE, KICK, WARN and IPBAN. The step is the number of earlier punishments of that player with the same reason id within ladder-reset-days; 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 staff_punishments, written by this module alone. A ban typed straight into LiteBans is not a step on the ladder. Punish through the menu and the ladder is always right.

Execution

The template for the step's type in commands 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 row is recorded, the issuer told, and the punishment published on the punishments channel: every server announces it to staff with exyliastaff.punish, or to everyone when broadcast.to-staff-only is off.

Configuration

plugins/ExyliaStaff/modules/punishments/config.yml

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%'
ladder-reset-days: 30
require-confirmation: true
broadcast:
  enabled: true
  to-staff-only: true

Reason ids must be unique across categories; the menus list categories and reasons in file order. %reason% in a template is the reason's display name, not its id. alert is a library effect played to staff on every announcement; it is empty by default.

Messages

modules/punishments/messages.yml: executed with %type%, %target% and %reason%; alert and broadcast with %staff%, %target%, %type%, %duration%, %server% and %reason%; never-played, unknown-reason, command-failed with %detail%, history-empty, self, no-target; the three ladder lines ladder-current, ladder-step and ladder-done with %index%, %type% and %duration%; duration-permanent.

Placeholders

Placeholder	Value
`%staff_punishments_total%`	Punishments the viewer has issued.
`%staff_punishments_today%`	Of those, issued today.