Sanctions

Sanction System Overview

XBans provides a unified sanction system with five core types: bans, mutes, warns, reports, and jails. Each sanction is stored with full metadata including the staff member who issued it, the reason, the timestamp, the duration, and the server it was issued on.

All sanctions support:

Temporary — Automatically expires after a specified duration
Permanent — Remains active until manually removed by staff
Cross-server sync — Propagated instantly across all servers in your network
History tracking — Every sanction is logged permanently for staff review

Duration Format

XBans uses a human-readable duration format for temporary sanctions. Durations are specified as a number followed by a unit suffix:

Suffix	Unit	Example
`s`	Seconds	`30s` = 30 seconds
`m`	Minutes	`5m` = 5 minutes
`h`	Hours	`12h` = 12 hours
`d`	Days	`7d` = 7 days
`w`	Weeks	`1w` = 1 week
`M`	Months	`1M` = 1 month

If no duration is specified, the sanction is permanent.

XBans uses a single command for both permanent and temporary sanctions. Pass a duration as the optional [time] argument to make a sanction temporary, or omit it for a permanent sanction. There are no separate /tempban, /tempmute, etc. commands.

Duration display automatically omits zero parts for readability. A 12-hour ban shows as "12h", not "12h 00:00". A 3-day 5-hour ban shows as "3d 5h", not "3d 05:00:00".

Common Flags

All sanction commands support two optional flags that can be placed before or after the player argument:

Flag	Description
`-s`	Silent mode — Suppresses the public broadcast. Only staff with the appropriate notification permission see the action.
`-server <name>`	Cross-server execution — Forwards the command to a specific server in your network. Useful for issuing sanctions on a server you're not currently connected to.

Example: /ban -s Steve 7d Cheating -server lobby bans Steve silently and forwards the command to the lobby server.

Sanction Templates

Templates are predefined sanction shortcuts that combine a duration and reason into a single token. Use them with the @template_name syntax in any sanction command in place of the duration/reason arguments.

Templates are configured in config.yml under the templates section:

templates:
  cheat: "ban 30d Cheating"
  hack: "ban Hacking - Permanent"
  spam: "mute 1d Spam / Flood"
  toxicity: "mute 12h Toxic behavior"
  evasion: "ban 60d Sanction evasion"

Usage:

/ban <player> @cheat
/mute <player> @toxicity
/ban <player> @hack

Templates resolve to their configured action, applying both the duration and reason in one keystroke. They are tab-completed alongside regular durations.

Bans

Bans prevent a player from joining the server entirely. When a banned player attempts to connect, they see a kick screen showing the reason, the staff member who banned them, and the remaining duration (if temporary).

/ban [-s] <player> [time] [reason] [-server <name>]
/unban [-s] <player> [-server <name>]

Omit [time] for a permanent ban. Provide a duration (e.g., 7d) to make the ban temporary — it expires automatically.

Examples:

/ban Steve Cheating — Permanent ban
/ban Steve 7d Toxic behavior — 7-day ban
/ban -s Steve 1d Spam — Silent 1-day ban
/ban Steve @cheat — Apply the "cheat" template
/unban Steve — Remove an active ban

Bans are synced across all servers. A player banned on one server is banned network-wide (when cross-server sync is enabled in XCore).

You can also use /unban-all <player> to lift all matching bans at once.

Sanctioning Offline / Never-Joined Players

XBans can sanction a player who has never connected to your server. Normally a name with no stored data fails with "player not found", forcing you to go through another plugin. With offline sanctions enabled (the default), /ban, /mute, and /warn resolve the UUID the player will have on their first join, so the sanction is enforced the moment they log in.

/ban Notch Ban evasion        # works even if Notch has never joined
/mute Notch 7d Spam / Flood
/warn Notch Rule violation

The matching removals — /unban, /unmute, /unwarn (and /unreport) — also resolve never-joined players, so a pre-emptive sanction can be lifted at any time.

How the UUID is resolved is controlled by offline-ban.uuid-source in config.yml:

Value	Behaviour
`auto` (default)	Premium (Mojang) UUID on online-mode servers, offline UUID otherwise
`online`	Always resolve the premium (Mojang) UUID — use for online-mode servers and premium proxies
`offline`	Always use the offline UUID — for cracked / offline-mode servers

IP bans and IP mutes cannot target a never-joined player, since XBans has no IP on record for them yet. Use a regular ban / mute / warn instead.

Set offline-ban.enabled: false to disable this and restore the old "player not found" behaviour.

IP Bans, IP Mutes & IP Range Bans

IP-level sanctions affect all accounts connecting from a specific IP address, making them effective against players who create new accounts to evade sanctions.

IP Ban

/ban-ip [-s] <player> [time] [reason] [-server <name>]
/unban-ip [-s] <player> [-server <name>]

When a player is IP-banned, the IP address associated with their account is blocked. Any player connecting from that IP will be denied entry.

IP Mute

/mute-ip [-s] <player> [time] [reason] [-server <name>]
/unmute-ip [-s] <player> [-server <name>]

Similar to IP bans but for chat. All players connecting from the muted IP are silenced.

IP Range Ban

/ban-ip-range [-s] <range> [reason] [-server <name>]

Bans an entire IP range using wildcard notation (e.g., 192.168.1.* or 10.0.*.*). The broadcast reports how many players are affected by the range ban.

IP sanctions target the player's last known IP. If the player connects from a different IP (e.g., using a VPN or changing network), the IP sanction won't affect them on the new IP. Combine IP sanctions with the security features (VPN blocking, alt-detection) for comprehensive enforcement.

Mutes

Mutes prevent a player from sending chat messages. Muted players can still join and play, but their messages are silently blocked (they see a notification explaining they are muted).

/mute [-s] <player> [time] [reason] [-server <name>]
/unmute [-s] <player> [-server <name>]
/unmute-all <player>

Mutes follow the same pattern as bans: pass a duration to make them temporary, omit it for permanent. The blocked-commands-when-muted config option lets you also block commands that bypass chat (e.g., /msg, /me).

The shadow-ban feature (shadow-ban.enabled in config) is an alternative form of mute: shadow-banned players can join and chat normally, but their messages are only visible to themselves.

Warns

Warnings are formal notices given to players for rule violations. Unlike bans and mutes, warns do not restrict gameplay by themselves. However, they provide a documented history of a player's behavior that staff can review. Warns expire after the configured warn-duration (default 30 days).

/warn [-s] <player> [reason] [-server <name>]
/unwarn [-s] <player> [id]

Warnings are displayed to the player as a notification when issued and on subsequent logins. Staff can view a player's warning history through /sanctions warns or via the player's profile (/profil <player>).

The /unwarn command without an [id] removes all active warnings for the target. Provide a specific warning ID (visible in the warn list GUI) to remove a single warning.

Warnings build a paper trail. The auto-sanctions system can automatically escalate to a mute or ban when a player accumulates too many warnings (see the configuration page).

Reports

The report system allows regular players to flag others for staff review. Reports are stored in the database and expire after the configured report-duration (default 30 days).

/report <player> [reason]
/unreport <player> [id]

Running /report <player> without a reason opens a reason-picker GUI where the player clicks the appropriate category (configurable in guis/report.yml; toggle with report.gui-enabled). Providing a reason inline reports directly and bypasses the GUI.

When a player submits a report:

The report is saved with the reporter's name, the target player, the reason, and the timestamp
Online staff members with the xbans.warden permission (Warden) receive a notification
If Discord webhooks are configured, a report notification is sent to your moderation channel
Reporters are subject to a cooldown (report-cooldown-ms) and a per-target limit (max-reports-per-player) to prevent spam

Staff can review reports via /sanctions reports. Like /unwarn, calling /unreport without an ID removes all reports on the target.

Jail System

The jail system confines players to a specific location as a punishment. Jailed players are teleported to the jail location and cannot leave the area until released or until their jail time expires. XBans supports multiple named jails — admins create them in-world and pass the jail name when sanctioning.

Sanction commands

/jail [-s] <player> [jail_name] [time] [reason] [-server <name>]
/unjail [-s] <player>
/sanctions jails

If [jail_name] is omitted, XBans uses the first available jail. The [time] argument follows the standard duration format — omit it to apply the jail.default-duration from config (default 1d).

Jail location management

/jail-create <name>     # Creates a jail at your current position
/jail-delete <name>     # Deletes a saved jail location
/jail-locations         # Lists all configured jails

How it works

An admin runs /jail-create <name> at the desired position to register a jail
When a player is jailed, their current location is saved (if jail.restore-location: true)
The player is teleported to the jail location
Movement outside the jail's move-radius is blocked
Per-jail restrictions enforce blocks on chat, commands, interaction, item drops, and PvP (configurable in jail.restrictions)
Whitelisted commands (jail.allowed-commands) remain usable when commands are restricted
When released (manually or by expiration), the player is teleported back to their saved location

The jail.restore-location config option controls whether a player's original position is saved and restored when they are unjailed. Enable this to return players to where they were before being jailed.

Jail messages have built-in anti-spam using a 3-second cooldown. If a jailed player repeatedly tries to leave the jail area, they won't be flooded with messages.

Players with xbans.exempt.jail cannot be jailed. The jail system can be globally disabled with jail.enabled: false.