Minecraft-Discord Account Linking Plugin (v2 — Full Spec)

A modern, high-performance Paper Minecraft plugin that securely links players' Minecraft accounts to their Discord accounts. This plugin runs an embedded Discord bot using JDA inside the same process and persists connections via a local SQLite database, requiring zero external setup!

---

🛠️ HOW THE SYSTEM WORKS

This is a unified plugin running two distinct services in a single Java Virtual Machine (JVM):

1. The Minecraft side (Paper command executors and asynchronous task threads).
2. The Discord side (JDA client logged in via your bot token, running its own asynchronous listener threads).

Because both sides live in the same process, they don't need socket networks, APIs, or webhooks — they call each other's Java methods directly and share the same SQLite connection pools!

Core Trust & Verification Flow (The Code Bridge)

The linking system bridges two independent identities securely without manual input of sensitive IDs:

1. Initiate on Discord: A Discord user types /link. JDA automatically supplies their permanent numeric Discord snowflake ID (e.g., 23871987349123847) from the interaction event itself.
2. Generate Code Ticket: The bot generates a random, clean, easily-readable 6-character code (excluding ambiguous letters like O, 0, I, 1) and saves a row: discord_id = <snowflake_id>, code = <random_code>, minecraft_uuid = NULL, verified = 0. This code acts as a single-use claim ticket tied strictly to that Discord account.
3. Redeem in Minecraft: The player joins the Minecraft server and types /verify <CODE>. Paper provides their trusted, authentic Minecraft UUID (player.getUniqueId()) directly from the server session.
4. Link Identity Pair: The plugin searches SQLite for an unverified, unexpired match. If found, it populates minecraft_uuid and flags verified = 1.
5. Role Assignment & Logs: The database trigger asynchronously prompts JDA to assign the "Verified" role to the Discord user, send a direct message confirmation, and write a verification record to the admin log channel.

Security Property: The verification code is the ONLY piece of data typed by a user. Nobody ever types their own UUID or Discord ID, entirely preventing account spoofing or identity theft!

---

⚡ ONLINE-MODE & MOJANG SECURITY

The cryptographic trustworthiness of this linking system depends directly on your server's online-mode setting:

online-mode=true (Recommended & Secure)

The server authenticates every connection directly with Mojang's servers on join. The UUID returned by player.getUniqueId() is guaranteed to belong to the genuine holder of that Minecraft account. Links are cryptographically secure and cannot be spoofed.

online-mode=false (Cracked/Offline Servers)

The server does not verify identity with Mojang. UUIDs are generated offline by hashing the username: UUID.nameUUIDFromBytes(("OfflinePlayer:" + username).getBytes()) Anyone can join with any username and hijack links. This plugin still runs perfectly on offline servers, but you should:

1. Ensure assume-online-mode is set to false in config.yml.
2. Acknowledge that links are only as trustworthy as your usernames (we recommend adding authentication plugins like AuthMe to cracked servers!).
3. Review warnings in your Discord logging channel, which flag links created while in offline-mode.

---

🎮 GEYSER & FLOODGATE BEDROCK COMPATIBILITY

This plugin natively supports Bedrock Edition & Pocket Edition players joining your Java Edition server via Geyser and Floodgate proxies.

Seamless Integration Logic:

1. Name Prefix Auto-Detection: Geyser typically prefixes Bedrock usernames with special symbols (e.g., *, ., or _) to avoid collisions with Java accounts. The plugin detects these prefix conventions during linking and tags them appropriately.
2. Deterministic UUID Matching: Floodgate uses deterministic UUID formats for Bedrock players (where the first 8 digits are zero, e.g., 00000000-0000-0000-...). The database seamlessly registers these UUIDs, allowing /unlink and /linkstatus to function correctly.
3. Optional Floodgate API Reflection Hook: If Floodgate is loaded on your server, the verification engine attempts to use reflection to consult the active FloodgateApi instance to verify Bedrock player statuses dynamically, requiring zero hard dependencies!

---

⚙️ CONFIGURATION (config.yml)

Set up your variables inside the config.yml located in your plugin's data directory:

# Discord Bot Secrets
bot-token: "YOUR_DISCORD_BOT_TOKEN"
guild-id: "YOUR_GUILD_ID"
verified-role-id: "YOUR_VERIFIED_ROLE_ID"
log-channel-id: "YOUR_LOG_CHANNEL_ID"

# Policy Settings
code-expiry-minutes: 10
rate-limit-seconds: 60
assume-online-mode: true
overwrite-existing-link: true

---

🤖 DISCORD PORTAL & BOT SETUP GUIDE

To use this plugin, you must create and invite a custom Discord Bot:

1. Create Application:
   • Go to the Discord Developer Portal.
   • Click New Application and give it a name (e.g., MyServerLinker).
2. Get Bot Token:
   • Navigate to the Bot tab in the sidebar.
   • Click Reset Token and copy the long token key. Save it securely — this must be pasted into your config.yml under bot-token.
3. Enable Intents:
   • On the same Bot tab, scroll down to Privileged Gateway Intents.
   • MUST ENABLE: Server Members Intent (required so JDA can lookup guild members to assign roles).
4. Authorize / Invite the Bot:
   • Go to the Installation or OAuth2 tab.
   • Select the bot and applications.commands scopes.
   • Under Bot Permissions, select:
     • Manage Roles (required to add the verified role to players)
     • Send Messages
     • Read Message History
   • Copy the generated URL and open it in a browser to invite the bot to your Discord Server.
5. Role Hierarchy Warning:
   • In your Discord Server settings, go to Roles.
   • Locate the role created automatically for your bot (it will match your Bot's application name).
   • Drag this bot role ABOVE the "Verified" role you want to assign to players!
   • Reason: JDA will throw an HierarchyException and fail silently to assign the role if the bot's own highest role is not positioned above the role it is trying to assign.

---

🧪 STEP-BY-STEP TEST PLAN

Follow these steps to verify your linking plugin operates flawlessly:

1. Configuring Secrets: Insert your Bot Token, Server Guild ID, and Verified Role ID into config.yml.
2. Server Boot: Start your Minecraft Server. Check console logs to verify SQLite creates links.db and the JDA Bot logs in successfully.
3. Request Link: In Discord, type /link. The bot should respond instantly with an ephemeral box showing your unique 6-character code (e.g., K3F9XZ).
4. Attempt verification: Join your Minecraft server and type /verify K3F9XZ.
5. Verify Success:
   • In-game chat should show a success message: "Successfully linked to Discord user YourName#0000".
   • Your Discord account should instantly receive the "Verified" role.
   • You should receive a friendly DM from the bot confirming the link.
   • The Discord log channel should receive a rich log embedding.
6. Verify Expiry: Wait 11 minutes (or configure code-expiry-minutes: 1) and try /verify <expired_code>. Server should reply with a clean invalid/expired code message.
7. Verify Cooldown: Try running /link twice within 60 seconds on Discord. The second attempt should be blocked by a visual cooldown timer.
8. Check Status: Type /linkstatus in Minecraft. It should fetch and display your linked Discord username.
9. Remove Link: Type /unlink in Minecraft. The row will clear from SQLite, and the bot will instantly strip your "Verified" role in Discord.