DiscordLink - Seamlessly Bridge Your Minecraft Server and Discord Community

DiscordLink
A powerful and user-friendly Discord verification system for your Minecraft server. Seamlessly link player accounts with automatic role assignment, nickname synchronization, and enhanced security features.

✨ Features

Simple Verification Process

• One-click code copying with visual feedback
• Easy-to-follow instructions
• Secure verification codes
• Automatic role assignment
• Force verification option for troubleshooting

Discord Integration

• Automatic nickname synchronization
• Custom role assignment
• Configurable messages
• Slash command support
• Discord member leave detection
• Role hierarchy validation

Advanced Security

• Two-Factor Authentication (2FA) system
• Unique verification codes
• Configurable code expiry
• Anti-abuse cooldowns
• Secure data storage
• Server selector restrictions for unverified players

User Experience

• Clean & modern messages
• Clickable commands
• Hover tooltips
• Detailed feedback
• Admin unlink command for staff management
• Comprehensive error handling

Requirements

• Minecraft 1.20.x - 1.21.4 (Paper/Purpur)
• Java 21 or higher
• Discord Bot Token
• Discord Server with admin access

⚙️ Setup Guide

1. Plugin Installation

• Upload DiscordLink.jar to your plugins folder
• Restart your server
• Configure config.yml

2. Discord Bot Setup

1. Create a bot at Discord Developer Portal
2. Enable "Server Members Intent"
3. Add bot to your server with required permissions:
   • Manage Roles
   • Send Messages
   • Read Messages/View Channels
   • Use Slash Commands
   • Manage Nicknames (optional, for nickname sync)
4. CRITICAL STEP: Set up the role hierarchy correctly
   • Make sure the bot's role is ABOVE the verified role in the list
   • This is REQUIRED for the bot to assign roles

3. Configuration

• Set your bot token in config.yml
• Set your server ID
• Set your verified role ID
• Configure 2FA settings
• Configure server selector restrictions
• Customize messages (optional)

Commands

Minecraft Commands

• /verify - Start verification process
• /verify force - Force verification reset when having issues
• /unlink - Unlink Discord account
• /2fa <code> - Complete two-factor authentication
• /discordlink unlink <player> - Admin command to unlink a player's account

Discord Commands

• /verify <code> - Complete verification process

Permissions

• discordlink.verify - Allow players to verify their account
• discordlink.unlink - Allow players to unlink their account
• discordlink.admin - Access to admin commands (including unlinking other players)
• discordlink.bypass.2fa - Allow players to bypass 2FA requirement
• discordlink.bypass.serverrestriction - Allow players to bypass server selector restrictions

⚡ Quick Start

1. Player types /verify in Minecraft
2. Clicks to copy their unique code
3. Uses /verify <code> in Discord
4. Gets automatically verified with role & nickname!
5. When rejoining, completes 2FA if enabled

️ Security Features

Two-Factor Authentication (2FA)

• Automatic verification code sent to Discord on join
• Player frozen until verification complete
• Configurable timeout and messages
• Permission-based bypass option

Server Selector Restrictions

• Prevent unverified players from using server selector
• Clear feedback messages
• Configurable restrictions

Discord Member Leave Detection

• Automatically unlink accounts when players leave Discord
• Server-side logging
• Prevents unauthorized access

Customization

Fully customize in config.yml:

• Message prefix
• All plugin messages
• Verification settings
• Nickname format
• Role management
• Security options
• 2FA settings
• Server selector restrictions

Support
Join our Discord Support Server for assistance!

Tips

• Keep the bot's role above the verified role
• Enable nickname sync for better server management
• Use custom messages to match your server's style
• Enable debug mode for troubleshooting
• Enable 2FA for enhanced security
• Configure server selector restrictions for controlled access

⚠️ Common Issues

Bot Can't Assign Roles

• Role Hierarchy Issue (Most Common Problem):
  • Discord uses a top-down role hierarchy system
  • The bot's role MUST be positioned ABOVE the verified role in Server Settings > Roles
  • If the bot's role is below the verified role, it cannot assign that role to users
• Check bot permissions (Manage Roles is required)
• Verify the correct role ID is in config.yml

Verification Process Failing

• If you see "Your account is already verified" in Minecraft but Discord shows errors:
  • Try using /verify force to reset your verification
  • Check server logs for specific error messages
• Ensure verification codes are being used before they expire

Nickname Sync Not Working

• Verify bot has "Manage Nicknames" permission
• Check role hierarchy - bot's role must be above user's highest role
• Server Owner Limitation: Discord does not allow bots to change the server owner's nickname
• Enable debug mode for detailed logs

Can't Find Guild/Server

• Double-check guild ID is correct (enable Developer Mode to see IDs)
• Ensure bot is in the server
• Check intents are enabled (Server Members Intent required)

2FA Not Working

• Verify Discord bot is properly configured
• Check permissions are set correctly
• Ensure player has verified their account first

Version History

v1.0.2 - Security & Reliability Update

• Added Two-Factor Authentication (2FA) system
• Added server selector restrictions for unverified players
• Added /verify force for resolving stuck verifications
• Implemented admin unlink command
• Enhanced verification code button with visual feedback
• Added Discord member leave detection
• Fixed 2FA and freeze state inconsistencies
• Improved role hierarchy validation

v1.0.1 - Java 21 Update

• Updated to support Java 21
• Performance optimizations and bug fixes

v1.0.0 - Initial Release

• Core verification system
• Nickname synchronization
• Role management
• Clickable codes
• Support for Minecraft 1.20.x - 1.21.4