Role sync

Role sync connects Discord roles to ranks on your Minecraft server. When someone gets a role in Discord, the server runs a command. When someone has a LuckPerms rank in the game, the bot gives them the matching Discord role. Both only work for players who have linked their accounts.

Set up

From Discord to the game

1. Create a rule for the role:

2. Allow the commands in the Minecraft server's config. With the default whitelist, the server rejects them.

# Spigot, Paper, Folia: plugins/mc-sync/config.yml
commands:
  mode: allow
  allow: ["lp user * parent add", "lp user * parent remove"]

# Fabric, Quilt, Forge, NeoForge: config/mc-sync.properties
commands.mode=allow
commands.allow=lp user * parent add,lp user * parent remove

3. Run /mcsync reload. On Forge before Minecraft 1.19, restart the server.
4. Give the role to a linked member. The command runs on every Minecraft server connected to this Discord server.

More on commands.mode is under Commands from Discord.

From the game to Discord

LuckPerms has to run on the Minecraft server. This direction is only available in the dashboard.

1. In the dashboard, open "Role sync" and go to "Ranks from Minecraft".
2. Pick the rank under "Rank in game" and the role under "Discord role".
3. Click "Add".
4. If several Minecraft servers are connected, pick one under "Which server decides the ranks?".

The bot updates the roles when a player joins the server and when their rank changes. It only adds and removes the roles listed here.

Settings

• {player} is replaced with the Minecraft name. Without it, everyone gets the same command.
• Commands go without the slash, 300 characters at most. One of the two commands may stay empty.
• The commands run with console permissions.
• /role-sync list shows all rules, /role-sync remove role: @VIP deletes one.

Problems

The command doesn't run in the game

• The person must be linked on this Discord server. They can check with /link show.
• The Minecraft server must accept the command under commands.mode and commands.allow, see Set up.
• Rejected commands show up in the command log. Set its channel with /notices channel purpose: commands.

People who already had the role don't get the rank

The command only runs when the role is added or removed. Anyone who had it before linking or before the rule existed gets nothing. Take the role away and give it again.

The Discord role isn't given

• The bot's role must sit above the role it should give, in the Discord server settings. Otherwise the dashboard shows "Bot role too low".
• The player must be linked and join the server after the mapping was created.

"Rank in game" is empty

The server hasn't reported a rank yet. Check that LuckPerms is running and the plugin is up to date (download). Ranks show up once a player joins or a rank changes.

You can't map a role

You can only map roles below your own highest role. Roles with moderation rights such as kick, ban or manage roles can only be mapped by an administrator.

The role keeps coming and going

Two Minecraft servers report different ranks for the same player. Pick one under "Which server decides the ranks?".