Configuration Reference

Complete guide to every XDiscordUltimate setting in config.yml. XDiscordUltimate uses YAML for configuration.

Configuration location: plugins/XDiscordUltimate/config.ymlThe file is generated automatically on first startup with sensible defaults. Edit it, then run /xdiscord reload — no restart required for most settings.

Quick Start

Generate the config

Start your server once. XDiscordUltimate drops a default config.yml into plugins/XDiscordUltimate/.

Set the minimum required values

At minimum, fill in discord.bot-token and discord.guild-id. Nothing works without them.

Enable the modules you want

Each feature lives under features.<module> and toggles with enabled: true|false.

Reload

Run /xdiscord reload (permission xdiscord.admin) to apply changes without restarting.

Enable debug mode (general.debug: true) to get verbose, per-module log output while you’re tuning things. Turn it back off for production.

Top-level structure

adminIDs: []          # Discord user IDs who receive admin alerts / DMs
general: {}           # Plugin-wide settings
features: {}          # One block per module (19 total)
discord: {}           # Bot token, guild, activity, channels
database: {}          # SQLite | MySQL | PostgreSQL
messages: {}          # Cross-module message formats
advanced: {}          # Thread pool, cache, rate limits
discord-console: {}   # Discord-side console mirror channel

Configuration Categories

Admin IDs

adminIDs:
  - "917098673127694428"

Discord user IDs (as strings) treated as plugin administrators. Members of this list receive admin-alert DMs and notifications. Enable Developer Mode in Discord (User Settings → Advanced → Developer Mode), right-click your profile → Copy ID.

General

general:
  debug: false
  default-language: "en_US"
  language: "en_US"
  check-updates: true

Key	Default	Description
`debug`	`false`	Verbose per-module logging.
`default-language`	`en_US`	Fallback locale for players without a preference.
`language`	`en_US`	Console/default language.
`check-updates`	`true`	Check for new releases on startup.

20 locales ship out of the box: en_US, ar_SA, cs_CZ, de_DE, es_ES, fr_FR, hi_IN, id_ID, it_IT, ja_JP, ko_KR, nl_NL, pl_PL, pt_BR, ru_RU, sv_SE, th_TH, tr_TR, vi_VN, zh_CN.

Discord (required)

discord:
  bot-token: "YOUR_BOT_TOKEN"
  guild-id: "YOUR_GUILD_ID"
  guild-name: "Our Discord Server"
  invite-url: ""
  activity:
    type: "PLAYING"
    text: "with %players%/%max% players"
    status: "ONLINE"
  commands:
    use-slash-commands: true
    legacy-prefix: "!"
  text-command-prefix: "!"
  channels:
    welcome: ""
    logs: ""
    chat: ""
    console: ""
    events: ""
    tickets: ""
    moderation: ""

Key	Description
`bot-token`	Bot token from the Discord Developer Portal. Required.
`guild-id`	Target server ID. Required. Slash commands register to this guild.
`guild-name`	Display name used in messages/embeds.
`invite-url`	Returned by the `/discord` command.
`activity.*`	Bot presence (`type`: PLAYING / WATCHING / LISTENING / COMPETING; `status`: ONLINE / IDLE / DO_NOT_DISTURB).
`commands.use-slash-commands`	Register Discord slash commands.
`commands.legacy-prefix` / `text-command-prefix`	Prefix for legacy text commands.
`channels.*`	Default channel IDs reused across modules.

Placeholders in activity.text: %players% (online), %max% (max slots).

Database

database:
  type: "sqlite"          # sqlite | mysql | postgresql
  sqlite:
    file: "data.db"
  mysql:
    host: "localhost"
    port: 3306
    database: "xdiscord"
    username: "root"
    password: "password"
    ssl: false

Tab Title
Tab Title
Tab Title

Zero-config. Just set type: sqlite and optionally the file name. Great for single servers.

Set type: mysql and fill in database.mysql.*. Pooled with HikariCP (max pool size 10).

Set type: postgresql and provide database.postgresql.* (host, port 5432, database, username, password).

The schema is created automatically on first run. A schema_versions table tracks migrations — future upgrades apply automatically.

Features (modules)

Every module is a block under features toggled by enabled. The 19 modules:

Key	Module
`chat-bridge`	Two-way chat sync
`server-logging`	Join/leave/death/command/advancement logs
`verification`	Discord↔Minecraft account linking
`server-control`	Run allowed commands from Discord
`admin-alerts`	TPS/RAM health alerts
`tickets`	Support ticket system
`moderation`	Ban sync, chat filter, reports
`bot-console`	Text-prefixed console in a channel
`announcements`	Cross-platform broadcasts
`player-stats`	Statistics tracking
`server-status`	Auto-updating status embed
`booster-perks`	Discord booster rewards
`welcome-dm`	Welcome DM on join/verify
`leaderboard`	Top-players embed
`activity-roles`	Playtime-based Discord roles
`voice-channels`	Player-count + dynamic voice channels
`economy-bridge`	Vault economy link (Discord transfers)
`server-ip`	`/ip` server address module
`whitelist`	Discord-driven whitelist requests

See the individual feature pages for each module’s full option set.

Verification

features:
  verification:
    enabled: true
    one-time-only: false
    kick-after-minutes: 0
    whitelist-mode: false
    verified-role: "Verified"
    verified-group: "verified"
    sync-nickname: true
    code-length: 6
    code-expiry-minutes: 5
    verify-cooldown-seconds: 30
    failed-attempt-cooldown-seconds: 5
    max-verify-attempts: 5
    verify-lockout-seconds: 300

Key	Default	Description
`one-time-only`	`false`	If true, a code can only be used once across the network.
`kick-after-minutes`	`0`	Kick unverified players after N minutes (`0` = off).
`whitelist-mode`	`false`	Require verification to play.
`verified-role`	`Verified`	Discord role granted on link.
`verified-group`	`verified`	LuckPerms group granted on link.
`sync-nickname`	`true`	Set the member’s Discord nickname to their IGN.
`code-length`	`6`	Characters in each verification code.
`code-expiry-minutes`	`5`	How long a code stays valid.
`verify-cooldown-seconds`	`30`	Cooldown after a successful verification.
`failed-attempt-cooldown-seconds`	`5`	Cooldown after each failed attempt.
`max-verify-attempts`	`5`	Failed attempts before lockout.
`verify-lockout-seconds`	`300`	Lockout duration once `max-verify-attempts` is hit.

Codes are generated with java.security.SecureRandom.

Chat Bridge

features:
  chat-bridge:
    enabled: true
    chat-channel-id: ""
    chat-channel: "minecraft-chat"
    minecraft-to-discord: true
    discord-to-minecraft: true
    filter-bot-messages: true
    skin-provider: "crafthead"
    auto-create-webhook: true
    use-webhook: false
    webhook-url: ""
    minecraft-format: "**%player%**: %message%"
    discord-format: "&7[&9Discord&7] &b%user%&7: &f%message%"
    show-mentions: true
    play-mention-sound: true
    convert-emojis: true
    strip-discord-formatting: false
    show-typing-indicator: true
    show-player-prefix: true
    show-player-suffix: false
    discord-username-format: "%prefix%%player%"

Set use-webhook: true (and auto-create-webhook: true) to post Minecraft chat as the player with their real skin avatar via the skin-provider (crafthead is most reliable and works with offline-mode names).

Tickets

features:
  tickets:
    enabled: true
    ticket-category: "Support Tickets"
    ticket-panel-channel: "ticket-logs"
    transcript-channel: "ticket-logs"
    support-role: "Support"
    max-open-tickets: 3
    auto-close-hours: 48
    auto-close-warning-enabled: true
    auto-close-warning-minutes: 60
    player-close: true
    save-transcript: true

Moderation

features:
  moderation:
    enabled: true
    sync-bans: true
    log-channel: "mod-logs"
    auto-moderate: true
    report-cooldown-minutes: 5
    require-verification-for-reports: true
    filter-words:
      - "example"
      - "regex:\\b(somepattern)\\b"

regex: entries are compiled as regular expressions. They’re powerful — always test a pattern before relying on it, and escape carefully.

Server Status

features:
  server-status:
    enabled: true
    channel-id: ""
    update-interval: 60
    message-id: ""

Leave message-id blank; the module creates the embed on first run and stores the ID so subsequent updates edit the same message in place.

Leaderboard

features:
  leaderboard:
    enabled: true
    channel-id: ""
    message-id: ""
    update-interval: 300
    top-players: 10
    default-type: "KILLS"
    custom-thumbnail: ""

Activity Roles

features:
  activity-roles:
    enabled: true
    sync-interval: 300
    remove-old-roles: true
    announce-promotion: true
    tiers:
      newcomer:
        display-name: "🌱 Newcomer"
        min-hours: 0
        role-id: ""
        color: "&a"
      regular:
        display-name: "⭐ Regular"
        min-hours: 10
        role-id: ""
        color: "&e"
      veteran:
        display-name: "💎 Veteran"
        min-hours: 50
        role-id: ""
        color: "&b"
      elite:
        display-name: "👑 Elite"
        min-hours: 100
        role-id: ""
        color: "&6"
      legend:
        display-name: "🏆 Legend"
        min-hours: 500
        role-id: ""
        color: "&d"

Set each tier’s role-id to the Discord role it should grant at that playtime threshold.

Voice Channels

features:
  voice-channels:
    enabled: true
    enable-status-channel: true
    status-channel-id: ""
    status-channel-format: "📊 Players: %online%/%max%"
    update-interval: 60
    enable-dynamic-channels: true
    category-id: ""
    hub-channel-id: ""
    dynamic-channel-prefix: "🎮 Gaming Room"
    max-dynamic-channels: 10
    user-limit: 0

Economy Bridge

features:
  economy-bridge:
    enabled: true
    currency-symbol: "$"
    currency-name: "coins"
    top-players: 10
    allow-transfers: true
    min-transfer: 1.0
    max-transfer: 1000000.0
    transfer-tax: 0.0

Requires Vault. Players must be verified before their Discord identity can move balance.

Booster Perks

features:
  booster-perks:
    enabled: true
    permission-group: "booster"
    sync-interval: 300
    use-native-detection: true
    booster-role-id: ""
    additional-booster-roles: []
    reward-commands:
      - "give %player% diamond 5"
      - "broadcast &d%player% &fis now boosting the Discord server! &d&lThank you!"
    remove-commands: []

Welcome DM

features:
  welcome-dm:
    enabled: true
    first-join-only: true
    verified-only: true
    plain-message: "Welcome, %player%! Your Discord account is linked."
    embed:
      title: "Welcome to %server_name%"
      description: |
        Hey **%player%**, welcome! Your accounts are linked.
      color: "#55FFFF"
      thumbnail: "%player_head%"
      image: ""
      footer: ""
      fields:
        - "Server IP|play.example.com|true"
        - "Website|example.com|true"
        - "Store|store.example.com|true"
        - "Need help?|Use /support in-game|false"

Fields are Title|Value|inline triplets.

Announcements

features:
  announcements:
    enabled: true
    default-channel: "announcements"
    show-title: true
    send-to-discord: false
    title-stay: 100
    title-fade-in: 10
    title-fade-out: 20
    prefix: "&6[&eAnnouncement&6] &f"
    sound: "ENTITY_EXPERIENCE_ORB_PICKUP"
    discord-color: "#FFD700"
    scheduled: {}

Server Control & Bot Console

features:
  server-control:
    enabled: true
    allowed-commands:
      restart: true
      stop: true
      kick: true
      tps: true
      list: true
    require-role: true
    control-role: "Server Admin"

  bot-console:
    enabled: true
    command-prefix: "!"
    allow-dm: false
    console-channel: "bot-console"

server-control and bot-console run real server commands from Discord. Gate them behind dedicated roles and only allowlist commands you’re comfortable exposing.

Admin Alerts

features:
  admin-alerts:
    enabled: true
    tps-threshold: 15.0
    ram-threshold: 90
    check-interval: 30
    dm-alerts: true
    alert-channel: "admin-alerts"

Alerts fire when TPS drops below tps-threshold or RAM usage exceeds ram-threshold%. Recipients are the adminIDs list (DMs) and/or the alert-channel.

Server IP & Whitelist

features:
  server-ip:
    enabled: true
    api-url: "https://your-tunnel-url.example"
    image-channel: "general"

  whitelist:
    enabled: true
    whitelist-channel: "whitelist"
    support-role: "Support"
    auto-whitelist: true
    dm-on-accept: true
    dm-on-decline: true

Messages

messages:
  minecraft-to-discord: "**%player%**: %message%"
  discord-to-minecraft: "&7[&9Discord&7] &b%user%&7: &f%message%"
  join-message: ":arrow_right: **%player%** joined the server!"
  leave-message: ":arrow_left: **%player%** left the server!"
  death-message: ":skull: **%player%** %death_message%"

Per-player localized strings live in plugins/XDiscordUltimate/lang/messages_<locale>.yml (20 locales). Use /language [locale] in-game to switch a player’s preference.

Advanced

advanced:
  thread-pool-size: 4
  cache:
    user-ttl: 60
    max-size: 1000
  rate-limit:
    commands-per-minute: 10

Tune thread-pool-size for large servers. The token-bucket DiscordRateLimiter honors commands-per-minute to stay under Discord API limits.

Discord Console (mirror)

discord-console:
  enabled: true
  channel-id: ""
  allowed-roles:
    - "Admin"
    - "Owner"

A separate read/write console mirror channel with role gating. Distinct from the in-Discord bot-console command runner.

Reloading

Most options apply live with /xdiscord reload. A full server restart is only required when changing:

discord.bot-token or discord.guild-id
database.type (or connection details)
Anything loaded once at startup by Libby/runtime dependencies

Next Steps

Features

Dive into each module’s dedicated page for behavior and examples.

Commands

Every command, alias, and permission in one place.

Database

Database backend setup for SQLite, MySQL, and PostgreSQL.

Verification

The account-linking system most other modules depend on.

​Configuration Reference

​Quick Start

​Top-level structure

​Configuration Categories

​Reloading

​Next Steps

Features

Commands

Database

Verification

Configuration Reference

Quick Start

Top-level structure

Configuration Categories

Reloading

Next Steps