SonoNiko
Plugins / PunishSystem / Documentation

Documentation PunishSystem

Installation, commands, permissions and configuration.

Installation

Single server

  1. Put PunishSystem-Paper.jar in the plugins folder and start the server.
  2. Paste your license-key (customer area) into plugins/PunishSystem/config.yml.
  3. Restart. The SQLite database is created automatically.

Velocity network

  1. Put PunishSystem-Velocity.jar on the proxy and the license-key in its config.yml.
  2. Put PunishSystem-Paper.jar on every server behind the proxy, with mode: backend (no license needed there).
  3. Set the same MySQL/MariaDB database in every config.yml:
database:
  type: mysql
  host: 127.0.0.1
  port: 3306
  name: punishsystem
  user: punish
  password: "your-password"

The proxy checks bans on join and handles commands and appeals. The Paper servers enforce mutes (Velocity can't block chat from modern clients) and open the history menu.

Commands

Command What it does
/ban <player> [duration] [reason] [-s] Ban (no duration = permanent)
/tempban <player> <duration> [reason] Temporary ban
/ipban <player\|ip> [duration] [reason] IP address ban
/unban <player\|ip> [reason] Remove the ban (IP ban too)
/mute · /tempmute · /unmute Mutes
/warn <player> [reason] · /unwarn <player> Warnings
/kick <player> [reason] Kick
/punish <player> <template> Escalating punishment
/history <player> History (menu)
/alts <player> Accounts that used the same IPs
/punishsystem reload · info Reload config · status

Durations: 30m, 12h, 7d, 2w, 1mo, 1y, also combined (1d12h). perm = forever. -s: only staff see the announcement.

Permissions

Permission What it allows
punishsystem.ban · tempban · ipban · unban Bans
punishsystem.mute · tempmute · unmute Mutes
punishsystem.warn · unwarn · kick Warnings and kicks
punishsystem.punish + punishsystem.punish.<template> Templates (or punishsystem.punish.*)
punishsystem.history · alts History and alts
punishsystem.seeip See full IPs
punishsystem.silent Use -s
punishsystem.notify See silent announcements and appeal decisions
punishsystem.alerts Banned alt alerts
punishsystem.exempt Can't be punished
punishsystem.punishsystem reload and info
punishsystem.staff Starter pack for helpers (Paper only)

Templates and warnings

In config.yml each template has a reason and a list of steps. Every repeat offense moves to the next step:

templates:
  hack:
    reason: "Modified client"
    steps: ["ban 7d", "ban 30d", "ban perm"]

Warnings trigger automatic actions:

warnings:
  expire-days: 30
  actions:
    3: "mute 1h"
    5: "ban 1d"

Discord appeals

You need the SonoNiko Tickets bot with Premium active on your Discord.

  1. Bot dashboard → Integrations: create the API key.
  2. Dashboard → Appeals: choose the category and enable appeals.
  3. In config.yml (on the proxy if you run a network):
language: en
appeals:
  enabled: true
  api-key: "tb_..."
  discord: "discord.gg/yourserver"

A banned or muted player sees a code and types /appeal code:XXXXXXXX on Discord. Staff get a ticket with the punishment and history and press Accept or Deny. If accepted, the punishment is lifted in game within about 20 seconds.

In the dashboard you can also require that only the owner of the punished account can appeal (the account must be linked to Discord with DiscordLink).

Linked accounts

The plugin stores the IPs each player uses. /alts shows the other accounts, with banned ones in red. With alts.block-banned-alts: true, anyone joining from the same IP as a banned account is blocked. Be careful with families and shared networks.

Troubleshooting

"in modalità backend serve MySQL": servers behind Velocity must use the same database as the proxy.

Mutes don't work on the network: make sure PunishSystem is on every Paper server with mode: backend.

Appeals don't reach Discord: /punishsystem info shows how many punishments are waiting to be sent. The console shows the reason (API key, Premium not active, appeals disabled in the dashboard).