Rank Synchronization

Rank Synchronization

Rank sync maps your LuckPerms permission groups to Discord roles. When a player's rank changes in Minecraft, their Discord roles update to match — and vice versa on login.

---

Requirements

• LuckPerms must be installed on the server. Without it, rank sync is silently disabled.
• Players must have a linked account.

---

How It Works

1. The plugin reads the player's LuckPerms groups.
2. Each group is looked up in the configured mappings list.
3. Matching Discord role IDs are collected, sorted by priority (highest first).
4. If remove-old-roles is true, all previously mapped roles are removed first.
5. The new roles are assigned via the Discord API.
6. Nickname is updated if nickname sync is enabled.

Rank sync triggers on:

• Player login (sync-on-join: true)
• Successful account link (sync-on-link: true)
• Periodic automatic sync (auto-sync)
• Admin command: /uxmdiscordsync forcesync <player>

---

Configuration

All rank sync settings live in rank-sync.yml.

rank-sync:
  enabled: true

  sync-on-join: true          # Sync when the player joins the server
  sync-on-link: true          # Sync immediately after account linking
  sync-interval: 300          # Seconds between automatic syncs for all online players

  remove-old-roles: true      # Strip old mapped roles before assigning new ones

  # Map each LuckPerms group to a Discord role
  rank-mappings:
    - minecraft-group: "admin"
      discord-role-id: "DISCORD_ROLE_ID"
      priority: 100
      post-link-commands:     # Commands run when this rank's player links their account
        - "broadcast %player_name% linked as admin!"
    - minecraft-group: "moderator"
      discord-role-id: "DISCORD_ROLE_ID"
      priority: 90
    - minecraft-group: "vip"
      discord-role-id: "DISCORD_ROLE_ID"
      priority: 50
    - minecraft-group: "member"
      discord-role-id: "DISCORD_ROLE_ID"
      priority: 1

Priority

Priority determines the order in which roles are compared when a player has multiple groups. Higher priority groups take precedence for things like nickname formatting. It does not limit which roles are assigned — all matching roles are assigned.

remove-old-roles

When set to true, any Discord roles that exist in the mappings list but are no longer matched by the player's current groups are removed. Set to false to accumulate roles without removing them.

post-link-commands

Commands listed under a mapping entry run once when a player with that group first links their account. Useful for one-time rewards or announcements.

Available placeholders:

• %player_name% — Minecraft username
• %player_uuid% — Minecraft UUID
• %discord_id% — Discord user ID
• %discord_name% — Discord username

---

Nickname Synchronization

Rank sync integrates with the nickname system. See Nickname Synchronization for the full configuration.

Quick reference:

nickname-sync:
  enabled: true
  format: "%player_name% (@%server_name%)"   # The format to apply as the Discord nickname
  max-length: 32
  truncation-suffix: "..."

---

Admin Commands

/uxmdiscordsync forcesync <player>

Forces an immediate rank and nickname sync for the specified player. Requires uxmdiscordsync.admin.

---

Audit Log

When audit-log is enabled, each rank sync event is recorded with:

• Player UUID and name
• Discord ID
• Groups before and after
• Roles assigned and removed
• Timestamp

See Logging for webhook configuration.

---

Troubleshooting

Problem	Likely Cause
Roles not assigned	Bot role is lower in hierarchy than the target role
Wrong roles assigned	Group name mismatch (case-sensitive)
Sync not triggering	Player account not linked
LuckPerms not found	LuckPerms not installed or loaded before this plugin

Discord role hierarchy: The bot's own role must be positioned above any role it needs to assign or remove. Drag the bot's role above your server ranks in Discord → Server Settings → Roles.