Nickname Synchronization

Nickname Synchronization

Nickname sync automatically sets a Discord member's server nickname to reflect their Minecraft identity. It runs whenever rank sync runs.

---

Requirements

• LuckPerms is needed if you use %primary_rank% or %all_ranks% in the format.
• Players must have a linked account.
• The bot must have Manage Nicknames permission.
• The bot's role must be above the members whose nicknames it manages. The bot cannot change the nickname of the server owner.

---

Configuration

Nickname sync is configured inside rank-sync.yml:

nickname:
  enabled: true
  format: "%player_name%"       # Template for the Discord nickname
  max-length: 32                # Discord's maximum is 32 characters
  truncation-suffix: "…"        # Appended when the formatted name is too long
  reset-on-unlink: true         # Remove nickname when player unlinks

---

Format Placeholders

Placeholder	Description	Example
%player_name%	Minecraft username	Steve
%discord_name%	Discord username	steve#0000
%server_name%	Server name from config	Survival
%primary_rank%	Highest-priority LuckPerms group	admin
%all_ranks%	All groups joined by comma	admin, vip

Example Formats

format: "%player_name%"                        # → Steve
format: "[%primary_rank%] %player_name%"       # → [admin] Steve
format: "%player_name% (%server_name%)"        # → Steve (Survival)

---

Truncation

Discord limits nicknames to 32 characters. If the formatted result exceeds max-length, the plugin truncates it and appends the truncation-suffix.

Example:

• Format: [LongRankName] VeryLongMinecraftUsername
• Result after truncation (32 chars with …): [LongRankName] VeryLongMinecraf…

---

When Nicknames Sync

Nicknames are updated at the same time as rank sync:

Trigger	Config Key
Player joins the server	sync-on-join: true
Player links their account	sync-on-link: true
Periodic auto-sync	auto-sync.enabled: true
Admin force-sync	/uxmdiscordsync forcesync <player>

---

Reset on Unlink

When reset-on-unlink: true, the plugin clears the Discord nickname back to the member's default Discord username when they unlink their account. If false, the nickname remains until changed manually.

---

Troubleshooting

Problem	Likely Cause
Nickname not changing	Bot lacks Manage Nicknames or its role is too low
Server owner's nickname unchanged	Discord does not allow bots to change the owner's nickname
%primary_rank% shows empty	LuckPerms not installed, or player has no group
Nickname truncated unexpectedly	Format + data exceeds 32 characters