Skip to main content

​
Getting Started with XDiscordUltimate

Get XDiscordUltimate connected to your Discord guild in a few minutes. You will need a Discord application with a bot token and privileged intents - see Bot Setup if you do not have one yet.
1

Prerequisites

Before installing XDiscordUltimate, ensure you have:
  • A Spigot or Paper server running Minecraft 1.16.5-1.21.x
  • Java 17 or higher on the server host
  • A Discord bot with its token (create one in the Developer Portal)
  • Server administrator access (console or op)
  • The guild ID of the Discord server you want to bridge
2

Download

Download the latest release from GitHub Releases.
A single universal JAR works on both Spigot and Paper across all supported Minecraft versions - no per-version or per-platform downloads.
3

Install

Place the downloaded JAR in your server’s plugins folder.
cp XDiscordUltimate.jar /path/to/server/plugins/
4

Configure

Start the server once to generate the default config at plugins/XDiscordUltimate/config.yml, then stop it. Edit the file and set the two required values plus at least one channel ID:
discord:
  # Required - the bot token from the Developer Portal
  bot-token: "YOUR_BOT_TOKEN_HERE"
  # Required - right-click your server in Discord -> Copy ID (Developer Mode must be on)
  guild-id: "123456789012345678"

features:
  chat-bridge:
    enabled: true
    # Channel ID where in-game chat is mirrored and Discord chat is relayed in
    chat-channel-id: "123456789012345678"
The plugin will not boot without discord.bot-token and discord.guild-id. Everything else has safe defaults.
5

Restart Server

Start the server again. XDiscordUltimate loads its runtime dependencies (JDA, HikariCP, database drivers) via Libby on first boot, so the initial startup takes a few seconds longer than usual.
# Stop and restart your server
The Discord bot should come online in your guild within a few seconds.
6

First Verification

To link a Minecraft account to Discord:
  1. A player runs /verify in-game to receive a one-time code
  2. The player uses the /verify slash command in Discord and enters the code
  3. The accounts are linked - the player can now use ticket, stats, and other linked features
See Verification for the full flow, including the new /unlink command added in 1.2.0.

​
Next Steps

Bot Setup

Create the Discord application and grant the privileged intents the bot needs.

Configuration

Tune the 19 feature modules, channels, and database connection.

Features

Browse the full module catalog and enable what you need.

First Run Checklist

Verify every module is wired up correctly.

​
Troubleshooting

Check your server logs for error messages. Common causes:
  • Java 17+ required. Run java -version on the host. The Gradle build targets Java 16 for compatibility, but the runtime needs 17+.
  • First-boot delay is normal. Libby downloads JDA, HikariCP, and the database drivers on first startup. If the server has no internet access on first boot, dependency download fails and the plugin will not enable.
  • Corrupt JAR. Re-download from Releases and verify the file size matches.
The bot shows as offline or never connects:
  • Verify discord.bot-token is correct and has no trailing whitespace. Reset the token in the Developer Portal if unsure.
  • Enable the three privileged intents in the Developer Portal under Bot > Privileged Gateway Intents: MESSAGE CONTENT, SERVER MEMBERS, and PRESENCE. The chat bridge, mentions, verification, and activity features all require these.
  • Confirm the bot was invited to the guild matching discord.guild-id and is not banned or restricted.
See Bot Setup for the full walkthrough.
Linking fails or codes are rejected:
  • Confirm the verification module is enabled: features.verification.enabled: true
  • Ensure the bot has Manage Roles and Manage Nicknames permissions in the guild so it can apply link roles and re-sync nicknames.
  • Check features.verification.verify-cooldown-seconds - players who fail repeatedly hit the cooldown and lockout added in 1.2.0.
  • The bot must be able to read and send DMs to deliver codes if DM delivery is enabled.

​
Need Help?

Community Support

Join the XreatLabs Discord for community support, or email official@xreatlabs.space.