Sanctions

The sanctions module replaces a classic ban plugin: it handles bans, IP bans, mutes, kicks and warns, keeps a record per player and automatically applies thresholds based on the warn score. Its options live in config/sanctions.yml, its commands in commands/sanctions.yml.

Common arguments

Several commands accept global arguments, placed anywhere on the line:

Argument	Effect	Commands
-silent	No public announcement (only staff is notified)	ban, tempban, unban, ipban, iptempban, ipunban, mute, tempmute, kick, warn
-template=<name>	Picks the ban screen template (bans/<name>.txt)	ban, tempban, ipban
-soft / -hard	Forces a soft or hard mute	mute, tempmute
-D	Delayed mute: it starts on the player’s next login	mute, tempmute

-silent on a ban requires cobaltstaff.bans.silent (cobaltstaff.ipban.silent for an IP ban), -template requires cobaltstaff.bans.template-overwrite (or cobaltstaff.ipban.template-overwrite), -soft/-hard requires cobaltstaff.mutes.override-softhard.

Durations

Durations accept 30s, 10m, 2h, 7d, 2w, 1M, 1y, the 7 DAY form and combinations such as 1d12h. perm, permanent or -1 mean “permanent”. They are displayed in a readable form.

Warns

A warn has a severity worth a number of points. The sum of the points of active warns is the player’s score; each threshold reached triggers actions.

/warn [severity] <player> [reason] [-silent]

Without a severity, a selection menu opens. Default severities:

Severity	Points	Expires after
LEGER (light)	1	2 weeks
MOYEN (medium)	2	1 month
GRAVE (serious)	4	3 months
CRITIQUE (critical)	6	never

Each severity can have a default reason (warn without a reason), allow or forbid overriding that reason, and define the item shown in the menu.

Thresholds

Default thresholds:

Score	Action	Undone when the warn is removed
3	1 h mute	unmute
5	1 day ban	unban
8	7 day ban	unban
12	permanent ban	unban

Each threshold is a list of actions (hooks format) with a rollback-command, run when the warn is deleted or its appeal accepted. The threshold label is shown to the player (“4/5 points, next: 1 day ban”).

The trigger mode is set with warnings.threshold-mode:

ALL (default)

Each warn re-runs all thresholds reached by the current score.

HIGHEST

Only the highest threshold reached is run.

CROSSED

Only the thresholds crossed by this warn (between the old and new score) are run.

Other actions can be tied to each warn (warnings.actions, filterable by severity). Players are told about their unread warns on login (or on every login with always-notify: true).

Managing warns

• /warns get <player> and /warns gerer <player>: list and management (expire, delete).
• /meswarns: players view their own warns and can appeal.
• /warns appels: pending appeals.

Bans

Command	Usage
/ban	<player> <reason> [-silent] [-template=<template>]
/tempban	<player> <duration> <reason> [-silent] [-template=<template>]
/ban prolonger, /ban reduire	<player> <duration>
/unban	<player> <reason> [-silent]
/bans gerer	Active bans (menu)

• Fixed reasons (bans.fixed-reasons): as soon as one reason is defined, the free-text reason is replaced by a choice (/ban <player> <reason>), and a menu opens when no reason is given. Each fixed reason sets the type (PERM_BAN or TEMP_BAN), duration, screen template, item and description.
• Login alert: when a banned player tries to join, staff with cobaltstaff.bans.notifications is notified (at most once per minute per player by default).
• Limits: tempban duration is capped by the cobaltstaff.bans.tempban.limit.<duration> permissions, extensions by cobaltstaff.bans.extendban.limit.<duration> (see Permissions).

Screen templates

Disconnect screens are MiniMessage text files in bans/. Four templates are bundled: permanent, temporaire, ip-permanent, ip-temporaire (written in French: edit them to translate). Add your own (bans/<name>.txt) and pick them with -template=<name> or in fixed reasons.

Variable	Content
%target%	Banned player
%issuer%	Staff member
%reason%	Reason
%duration%	Total duration
%remaining%	Time left
%expiration%	End date (“never” if permanent)
%date%	Sanction date
%id%	Sanction number
%ip%	Targeted IP (IP bans)

IP bans

/ipban <player|ip|range> <reason> [-silent] [-template=<template>]
/iptempban <player|ip|range> <duration> <reason> [-silent]
/ipunban <player|ip|range> [reason] [-silent]
/checkip <player>
/ipbans [-players]

An IP ban targets an address, a player’s last known address or a CIDR range (IPv4 and IPv6). Before applying the ban, CobaltStaff lists the affected players (based on their last known IP) and asks for confirmation, in chat or in a menu (ipbans.confirmation: CHAT | GUI | DISABLED).

Tip

The cobaltstaff.hideip permission hides a player’s IP in staff menus; cobaltstaff.examine.view-ip is required to see it.

Mutes

/mute <player> <reason> [-soft|-hard] [-D] [-silent]
/tempmute <player> <duration> <reason> [-soft|-hard] [-D] [-silent]
/mute prolonger <player> <duration>     /mute reduire <player> <duration>
/unmute <player> [reason]

• Hard mute: the player is told and their messages are refused.
• Soft mute: the player does not know they are muted; they see their own messages, but nobody else receives them. The default behaviour is set with mutes.default-soft-mutes.
• Delayed mute (-D): if the player is offline, the mute only starts on their next login, so they serve the full duration.
• Blocked commands: while muted, the private messaging and chat commands listed in mutes.blocked-commands are refused (multi-word commands allowed, e.g. cmi msg).
• /mutes gerer, /mesmutes, /mutes appels: management menu, own mutes and appeals.

Kicks

/kick <player> [reason] [-silent]

Predefined reasons (kicks.reasons) open a selection menu when no reason is typed; a single reason is applied directly. kicks.fixed-reason: true forbids free-text reasons.

Unified sanction menu

/sanction <player>

This menu offers ready-to-use motives. Each motive chains one or more steps (WARN with a severity, MUTE or BAN with a duration, KICK). Bundled motives:

Motive	Steps
Insults	MOYEN warn
Spam / flood	LEGER warn
Advertising	1 day mute + MOYEN warn
Scam	GRAVE warn
Grief	GRAVE warn
Cheat	permanent ban
Threats	CRITIQUE warn

A motive’s default reason can be edited in the menu (sanction-menu.reason-editable). The menu is also available from a report’s management screen and from the player profile.

Player record

/infractions <player>        aliases /casier, /history
/infractions top [ban|mute|warn|kick|all]

The record gathers all of a player’s sanctions, newest first, with their status (active, expired, lifted, appeal accepted…). Other modules add their own lines (reports received, investigations). Displayed types and icons are set in infractions.types; /infractions top shows the most sanctioned players (28 by default).

Appeals

Warns, mutes and bans can be appealed from the menus:

1. The player opens their sanctions (/meswarns, /mesmutes) and files an appeal with a reason — permission cobaltstaff.<type>.appeals.create. A staff member can file an appeal for another player (…appeals.create.other), useful for a banned player.

2. Staff with cobaltstaff.<type>.appeals.notifications is notified.

3. A staff member accepts (…appeals.approve) or rejects (…appeals.reject) the appeal, with a reason if resolve-reason-enabled is on.

4. If accepted: the warn is cancelled (and the thresholds it triggered are rolled back), the mute or ban is lifted (unmute-on-approve, unban-on-approve). Extra commands can be run (on-approved-commands, on-rejected-commands).

<type> is warnings, mutes or bans. The appeal reason can be restricted to a list (fixed-reason, reasons).

Public announcements

With announce: true, every ban, mute, kick and warn is announced to all players, unless -silent is used. Staff always gets a notification (cobaltstaff.<type>.notifications permissions).

Import and migration

Command	Effect
/cobaltstaff import litebans [severity]	Imports bans, mutes, kicks, warns and the name and IP history from LiteBans. Can be re-run without duplicates.
/bans migrer	Imports the vanilla server’s bans.
/ipbans migrer	Imports the vanilla server’s IP bans.

The LiteBans import requires cobaltstaff.bans.migrate. Since LiteBans has no severity, imported warns get the severity passed as argument, or import.litebans.warn-severity (LEGER by default).

Bypasses

Permission	Effect
cobaltstaff.bans.bypass	Cannot be banned
cobaltstaff.mutes.bypass	Cannot be muted
cobaltstaff.kicks.bypass	Cannot be kicked
cobaltstaff.warnings.bypass	Cannot be warned

Note

The staff hierarchy applies as well: a moderator cannot sanction a staff member of equal or higher rank.