DiscordRoleSync is a Minecraft plugin for syncing Discord roles and Minecraft permissions. This syncs Discord to Minecraft only, it is not both ways.
A list of managed Discord roles can be configured and linked o Minecraft groups. If a Discord user gets a role added, they will get added to the Minecraft group. If the user gets the role removed, they will be removed from the Minecraft group.
This can use both SQLite (automatically created, no setup needed) or MySQL. MySQL is recommended for stability on large servers.
This plugin has been tested on Minecraft versions 1.8.8 to 1.21.
Some features are optional and can be opted in or out from the config file.
- Sync roles from Discord to Minecraft groups. Users will be added/removed from Minecraft groups based on the Discord roles they have
- Add a Discord role to users that have been linked
- Control who can access your server (whitelist) using a Discord role
- Update user's Discord nicknames based on their Minecraft username
- Integration with PlaceholderAPI
You should first install Vault as this plugin will not work without it.
This plugin targets Java 11, however it has been reported working with Java 8. No support is provided with Java versions below 11.
Just copy the .jar to the plugins folder and run the server once to generate the config files. The plugin will error out due to no config, but that's expected on the first run. Go to the config.yml file and add your Discord bot token. To get one:
- Go to https://discord.com/developers/applications
- Click "new application" and put a name for your bot
- In the left sidebar, click "Bot"
- Click "add bot" and confirm
- In this page, you can change your bot's picture and username.
- Turn on "Server Members Intent" - it won't work without this as the bot needs to work with the member list
- Click copy token and paste it in the config file. Anyone with your token can log in as your bot, so you should keep it secret as if it were a password.
- Go back to the Discord developer website and on the left sidebar, click "OAuth2"
- Select "bot" as a scope then copy the link
- Go to the link you just copied to add the bot to your server
Don't forget to put all roles in the configs. You should put the role IDs, not the role names. To get the ID you should enable developer mode in Discord, then right-click the role and copy ID (it's a number of approximately 18 digits). The same thing applies for the server ID and channel IDs.
It's pretty simple: all your users should use the /link command in Discord to link their Minecraft account:
/link myMCusername
As soon as they do this, their roles will keep synchronized while they are in the server. When your users get the Discord role, they will automatically get the permission plugin group. Updates are instant.
Staff can also use the /admlink command to force link a user:
/admlink discordID mcUsername
The Discord ID of the user is a 17 to 20-digit number.
The /info and /unlink commands are available for staff use. Both accept Discord IDs or Minecraft usernames. By default, these three admin commands are available for everyone that has the MANAGE ROLES Discord permission. This can be modified in your Discord server.
The users need to remain in the Discord server to keep their roles. If they leave the server or are unlinked with the /unlink command, they are removed from the whitelist and every role is removed from them.
If verification is enabled (requireVerification: true on the config), users will either get the code when they are kicked by whitelist (if whitelist management is enabled) or by typing /drs verify in the Minecraft chat. This code then needs to be sent in Discord using /verify <code>.
Currently, the languages supported (and bundled with the plugin) are:
- English (en_US)
- Portuguese (pt_BR)
- Italian (it_IT)
- French (fr_FR)
- Spanish (es_ES)
- Turkish (tr_TR)
- German (de_DE)
- Japanese (ja_JP)
- Russian (ru_RU)
If you want to add your language, you can copy the en_US.yml file and edit it to your language. If you are interested in having your translation bundled with the plugin, please contact me via Discord or make a merge request on GitLab, I'll be happy to include it :D
As updates to this plugin are released, only English and Portuguese are updated (as those are the languages I speak). Other languages might get out of date and will use English as a default. Please let me know if you'd like to help update these languages!
This plugin should work with every permission plugin that supports Vault.
Tested and confirmed working:
- LuckPerms (recommended)
- Ultra Permissions
- PermissionsEx (deprecated)
- PowerRanks
A note on PermissionsEx: I do not recommend using PermissionsEx as it is deprecated and does not support asynchronous permission adding. Performance might be worse when using it in large servers.
discordrolesync.reload: Use the /drs reload commanddiscordrolesync.botrestart: Use the /drs botrestart commanddiscordrolesync.notifyupdates: Users with this permission will be notified when they join if an update is available.
All users are permitted to use the /drs verify command
The PlaceholderAPI integration can be enabled by setting integrations.plugins.PlaceholderAPI to true in the config.
This will allow the Bot's status message to read from placeholders.
It also enables a Placeholder Expansion for this plugin, with the following placeholders supported:
%drs_linked_users%: the number of linked users%drs_link_status%: if the user is linked or not%drs_discord_username%: the Discord username of the user, if linked. Empty if not linked.%drs_discord_display_name%: the Discord nick of the user, if linked. Empty if not linked.
PlaceholderAPI integration is new and might still need some improvements. Please let me know if you have a request or bug report.
The Geyser integration can be enabled by setting experimental.geyser.enableGeyserSupport to true in the config.
When enabled, linking to a username that starts with a dot (.exampleuser) will be treated as a Geyser user.
This is an experimental feature. Please let me know if you have a request or bug report.
This plugin is open source! The source code can be found on GitLab. Please see CONTRIBUTING.md for more information.
Contributions are more than welcome! I've recently picked up support for this plugin again, and am in the process of cleaning up the code. I'm not a Java expert, so feel free to make clean-up, opinionated contributions if you'd like.
If needed, you can reach me via GitLab or Discord. To report bugs or request features, you can either create an issue in GitLab or contact me via Discord.
Please node that in offline mode servers, linking usernames is case-sensitive.
While this plugin works with offline servers, it might conflict with "login plugins" that change a user's UUID after they join. Please try the userUUIDMode FALLBACK or MANUAL options if you use login plugins.
If you swap between offline and online (or vice-versa), either via the UUID mode config or server mode change, you'll need to delete the database. If you are using SQLite, just delete the database.db file. If you are using MySQL, execute DROP TABLE syncbot_discordmcusers;, replacing syncbot with the prefix in your config.yml file if you have changed it.