Account Linking

Account Linking

The account linking system lets players connect their Minecraft identity to their Discord account. Once linked, all other features (rank sync, nicknames, boost rewards, 2FA, level rewards) work automatically.

---

How It Works

Player                   Minecraft Server              Discord
  │                            │                          │
  ├─ /link ──────────────────► │                          │
  │                            │ Generate 6-digit code    │
  │ ◄──── "Your code: 123456" ─┤                          │
  │                            │                          │
  │                            │        ◄─── Click "Link Account" button
  │                            │                          │
  │                            │        ◄─── Enter code in modal
  │                            │                          │
  │                            │ Validate code ──────────►│
  │                            │ Store linked_account      │
  │                            │ Assign linked roles ─────►│
  │ ◄──── "Account linked!" ───┤                          │

1. The player runs /link in Minecraft.
2. The server generates a unique 6-digit code and stores it in the database with an expiry time.
3. The player goes to the designated Discord linking channel and clicks Link Account.
4. A modal appears where they type in the 6-digit code.
5. The plugin validates the code and, on success:
   • Creates a record in the linked_accounts table.
   • Assigns all configured linked-role-ids in Discord.
   • Runs any configured post-link commands.
   • Sends the player a confirmation message (in-game and optionally via DM).
   • Records an audit log entry.

---

Configuration

All linking settings live in config.yml under discord.linking.

discord:
  linking:
    channel-id: "1234567890"       # Channel where the Link Account button is posted
    linked-role-ids:               # Discord roles given to every linked player
      - "9876543210"
    code-expiration: 300           # Seconds the code remains valid (default: 5 minutes)

    # Customise the embed posted in the linking channel
    embed:
      title: "Link Your Account"
      description: "Run /link in-game to get your code, then click the button below."
      color: "#5865F2"
      footer: "Codes expire after 5 minutes."

    # Customise the button
    button:
      label: "Link Account"
      emoji: "🔗"

    # Customise the code-entry modal
    modal:
      title: "Enter Verification Code"
      input-label: "6-Digit Code"
      input-placeholder: "123456"

    # Commands run on the server after a successful link
    # Supports %player_name%, %player_uuid%, %discord_id%
    post-link-commands:
      - "say Welcome to the server, %player_name%!"

---

Rate Limits & Security

Limit	Default	Config Key
Code requests per minute	3 per player	security.rate-limit.code-generation in advanced.yml
Code expiry	300 seconds	discord.linking.code-expiration
Cooldown between /link uses	30 seconds	Hardcoded

Codes are one-time-use. Once redeemed, the code is immediately deleted from the database. Expired codes are automatically cleaned up.

---

Unlinking

Players can unlink their account with /unlink. When an account is unlinked:

• The linked_accounts record is deleted.
• All linked-role-ids are removed from the Discord member.
• The Discord nickname is reset (if nickname sync is enabled).
• An audit log entry is created.

If server-mode is set to shared, unlinking on any server unlinks on all servers. If set to separate, only the current server's link is removed.

---

Admin Commands

/uxmdiscordsync forcelink <player> <discordId>   # Link a player manually
/uxmdiscordsync forceunlink <player>             # Unlink a player forcibly

These require the uxmdiscordsync.admin permission.

---

Multi-Server Linking Modes

Configured in config.yml:

server:
  name: "Survival"
  link-mode: shared     # "shared" (once across all) or "separate" (per-server)

Mode	Behaviour
shared	One link works on all servers using the same database
separate	Players must link separately on each server

---

Linking Channel Setup Tips

1. Create a read-only channel (deny Send Messages for @everyone).
2. Set the channel-id in config.
3. On first start (or after /uxmdiscordsync reload), the plugin posts the link embed with the button automatically.
4. The embed is persistent — the bot will repost it if it is deleted.

---

Events Logged

When audit-log is enabled, the following events are written to the audit webhook:

Event	When
LINK	Successful account link
UNLINK	Account unlinked (player or admin)
FORCE_LINK	Admin force-linked an account
FORCE_UNLINK	Admin force-unlinked an account

See Logging for webhook configuration.