Configuration

Configuration Overview

XBans is configured through config.yml located in plugins/XCore/addons/XBans/. The configuration is organized into logical sections covering each feature.

Most configuration changes can be applied with /xbans reload without a server restart. The exception is database table structure changes, which require a restart.

General Settings

# Enable debug logging
debug: false

# Cooldowns (in ms)
cooldowns:
  chat: 2_000
  command: 2_000

# Default warn duration
warn-duration: 30d

# Report duration
report-duration: 30d

# Require a reason for sanctions (ban, mute, warn, kick)
require-reason: false

# Max reports per player (prevents report spam)
max-reports-per-player: 5

# Cooldown between reports from same player (in ms)
report-cooldown-ms: 30_000

# Auto-purge inactive sanctions older than X days (0 = disabled)
auto-purge-days: 90

# Anonymous moderator (hides moderator name in broadcasts; Discord still shows real name)
anonymous-moderator: false

# Appeal URL shown on the ban kick screen (empty = no appeal line)
appeal-url: ""

The broadcast-permissions map (see below) controls who sees public sanction broadcasts per sanction type — leave a value empty to broadcast to everyone, or set a permission to restrict the broadcast to those who hold it.

Broadcast Permissions

broadcast-permissions:
  ban: ""
  mute: ""
  kick: ""
  warn: "xbans.notify.warn"
  report: "xbans.notify.report"

Empty value means "broadcast to all players". Setting a permission restricts who sees the broadcast. Common patterns:

  • Public bans, private warns/reports — Default config. Bans, mutes, and kicks are shown to everyone (deterrent effect); warns and reports stay quiet.
  • All private — Set every value to "xbans.notify.staff" for a staff-only experience.
  • Use -s per-command — Even with public defaults, individual sanctions can be issued silently with the -s flag.

Jail Configuration

jail:
  enabled: true
  # Default jail duration (empty = permanent)
  default-duration: "1d"
  # Radius around jail point where player can move (in blocks, 0 = stuck in place)
  move-radius: 5
  # Restrictions (true = blocked)
  restrictions:
    chat: false
    commands: true
    interact: true
    drop-items: true
    pvp: true
  # Whitelisted commands when jailed (only if commands restriction is true)
  allowed-commands:
    - "/msg"
    - "/r"
  # Restore player's previous location on unjail
  restore-location: true
  # Exempt permission
  exempt-permission: "xbans.exempt.jail"

Jail locations themselves are not stored in config.yml — they live in a separate file managed by /jail-create, /jail-delete, and /jail-locations.

When restore-location is true, XBans saves the player's exact position before teleporting them to jail. Upon release, they are teleported back to that saved location. If false, released players stay at the jail location.

Auto-Sanctions

The auto-sanctions system automatically escalates a player to a heavier sanction when they accumulate too many active warnings:

auto-sanctions:
  enabled: false
  thresholds:
    3: "mute 1d"
    5: "ban 3d"
    10: "ban"

The action format is "<type> [duration]" where the type is one of ban, mute, or jail. Omit the duration for a permanent sanction. The action is automatically applied to the warned player — no {player} placeholder is needed.

For escalations triggered by reports rather than warnings, see auto-report-escalation:

auto-report-escalation:
  enabled: false
  thresholds:
    3: "warn {player} Multiple reports received"
    5: "mute {player} 1d Too many reports"
    10: "ban {player} 7d Excessive reports"

Unlike auto-sanctions, this section uses raw command strings with the {player} placeholder — so any XBans sanction command (including jail) is valid here.

Regex-based escalation is also available via reason-escalation for upgrading sanctions whose reason matches a pattern (e.g., upgrade any reason containing "hack" to a permanent ban).

Templates & Predefined Reasons

# Predefined reasons (tab-complete suggestions)
reasons:
  - "Cheating"
  - "Bug exploitation"
  - "Sanction evasion"
  - "Toxic behavior"

# Predefined durations (tab-complete suggestions)
durations:
  - "6h"
  - "12h"
  - "1d"
  - "3d"
  - "1w"
  - "1M"

# Sanction templates (shortcuts for common sanctions)
# Usage: /ban <player> @template_name
templates:
  cheat: "ban 30d Cheating"
  hack: "ban Hacking - Permanent"
  spam: "mute 1d Spam / Flood"
  toxicity: "mute 12h Toxic behavior"
  evasion: "ban 60d Sanction evasion"

reasons and durations populate the tab-completer for sanction commands. templates are full-action shortcuts invoked with @name — see the Sanctions page for usage examples.

IPInfo Configuration

ipinfo:
  enabled: false
  token: ""

  # Cache duration for IP lookups (in minutes)
  cache-duration: 60

The cache prevents redundant API calls for the same IP address. Players reconnecting within the cache window are checked against the cached result instead of making a new API request.

Blocking rules are configured in the consolidated ip-security section (see below).

IP Security Configuration

All IP-based security rules (VPN, hosting/datacenter, mobile, ISP, and IP range blocking) are consolidated under a single ip-security section:

ip-security:
  vpn:
    enabled: false
    bypass-permission: "xbans.bypass.vpn"
  hosting:
    enabled: false
    bypass-permission: "xbans.bypass.hosting"
  mobile:
    enabled: false
    bypass-permission: "xbans.bypass.mobile"
  isp:
    enabled: false
    blocked-isps: []
  ip-range:
    enabled: false
    blocked-ranges: []

Each sub-section can be independently enabled or disabled. The bypass-permission fields allow specific players to connect even when blocking is active (e.g., staff members using a VPN). ISP and IP range blocking do not require the IPInfo API but benefit from having it enabled for accurate ISP name resolution.

GeoIP Country Blocking

geoip:
  enabled: false
  # Block mode: "whitelist" (only allow listed countries) or "blacklist" (block listed countries)
  mode: "blacklist"
  countries:
    - "XX"

GeoIP uses the free ip-api.com service — no API key needed. Country codes follow ISO 3166-1 alpha-2 (e.g., FR, US, BR).

Client & Version Security

client-security:
  enabled: false
  log-brands: true
  show-in-warden: true
  blocked-brands: []
  #  - "wurst"
  #  - "meteor"
  allowed-brands-only: []   # whitelist mode (leave empty to use blocked-brands)
  blocked-versions: []      # specific protocol numbers to block
  min-protocol-version: 0   # 0 = no minimum
  max-protocol-version: 0   # 0 = no maximum

Whitelist vs blacklist: if allowed-brands-only contains entries, it acts as a whitelist and blocked-brands is ignored. Otherwise, blocked-brands acts as a blacklist. Brand matching is case-insensitive partial match.

For protocol version numbers, see wiki.vg/Protocol_version_numbers.

AI Moderation Configuration

The AI moderation has two layers: the core ai-classifier (the Bayesian engine) and chat-ai (the chat-message moderation policy that uses it). Both can be configured independently.

ai-classifier:
  enabled: true
  min-confidence: 0.5
  show-in-warden: true
  auto-train-on-action: true
  auto-train-on-sanction: true

chat-ai:
  enabled: true
  min-confidence: 0.4
  monitored-categories:
    toxicity:
      reset-after: "1d"
      actions:
        1: "warn {player} {reason}"
        3: "mute {player} 1h {reason}"
        10: "ban {player} 7d {reason}"
    spam:
      reset-after: "6h"
      actions: { ... }
    scam:
      reset-after: "0"
      actions: { ... }
  notify-warden: true
  log-flagged: true
  history-size: 50
  report-evidence-action: "none"
  report-evidence-min-flagged: 2

The min-confidence setting is critical for balancing false positives and false negatives:

  • Lower (0.3-0.5) — More aggressive. Catches more borderline messages but may flag sarcasm or jokes.
  • Higher (0.6-0.8) — More lenient. Only catches clearly toxic messages. Fewer false positives.

report-evidence-action is a second-layer feature: when a player is reported, XBans scans their recent messages (up to history-size) and counts AI-flagged ones. If report-evidence-min-flagged is reached, the configured action runs (e.g., "mute {player} 1h Toxic messages detected via report").

Discord Configuration

discord:
  enabled: false
  webhook-url: ""
  notify-on:
    - ban
    - ban-ip
    - mute
    - kick
    - report
    - warn

The notify-on list controls which event types trigger a Discord webhook. Remove an entry to silence that event type. See the Discord Integration page for detailed setup instructions.

Alt-Detection Configuration

alt-detection:
  risk-scoring:
    enabled: false
    shared-ip-score: 30
    same-client-brand-score: 15
    same-country-score: 5
    # Threshold to trigger warden alert
    alert-threshold: 30
    # Threshold to trigger auto-action
    action-threshold: 50
    # Auto action when threshold reached: "kick", "ban <duration>", or empty for none
    auto-action: ""
  # Maximum alts per IP before auto-action (0 = disabled)
  max-alts-per-ip: 0
  # Action when max alts exceeded: "kick" or "ban <duration>"
  max-alts-action: "kick"

shared-ip-detection:
  enabled: true
  auto-ban-shared-ip: false
  whitelist-ranges:
    - "127.0.0.*"

Two complementary systems: risk-scoring assigns weighted points to multiple factors and triggers actions when thresholds are reached, while shared-ip-detection handles the simpler case of "this IP was used by a banned player". The whitelist-ranges list prevents false positives on shared infrastructure (NAT, school networks, etc.).

Moderation ToolsGUI Screens