🤖 RoleZ, Advanced Discord Integration Plugin for Minecraft

Important

RoleZ is a premium paid plugin. To acquire a license and use this plugin, please purchase it on BuiltByBit:
🛒 Click here to Purchase RoleZ on BuiltByBit

RoleZ is a powerful, high-performance Discord-to-Minecraft integration plugin designed for Spigot and Paper servers. It seamlessly bridges your Discord community with your Minecraft server through 2-way account linking, automatic LuckPerms rank synchronization, real-time Discord slash commands, webhooks logging, and PlaceholderAPI placeholders.

---

🌟 Key Features

• 🔗 2-Way Account Linking: Secure code-based verification system connecting Discord IDs with Minecraft accounts backed by SQLite.
• ⚡ Real-Time Rank Synchronization: Automatically syncs Discord roles to Minecraft LuckPerms parent groups in real time when roles are added or removed.
• 🤖 Native Discord Slash Commands: Fully integrated slash command suite (/link, /unlink, /ranksync, /rankunsync, /mcuser, /help).
• 📊 Comprehensive PlaceholderAPI Integration: Over 15+ custom placeholders for TAB, Scoreboards, Holograms, and Chat formats.
• 📜 Discord Webhook Audit Logger: Color-coded embed notifications sent directly to your Discord staff channel for all link, unlink, and rank sync actions.
• 🛡️ LuckPerms Native API Integration: Uses LuckPerms API with graceful fallback to console commands.
• ⏰ Automated Cleanup Scheduler: Background task (every 12 hours) automatically cleans up revoked roles and unlinked users.
• ⚙️ Fully Customizable Messages: Complete control over colors, prefixes, and translations via messages.yml.

---

🚀 Installation & Setup

Requirements

• Minecraft Server: 1.13+ (Spigot / Paper / Purpur)
• Java Runtime: Java 17 or higher
• Dependencies:
  • LuckPerms (Required for rank sync)
  • PlaceholderAPI (Optional)

Quick Start Guide

1. Place RoleZ-1.0.5.jar into your server's plugins/ directory.
2. Restart your server to generate the default configuration files.
3. Open plugins/RoleZ/config.yml and configure:
   • discord.token: Your Discord Bot Token (ensure GUILD_MEMBERS & MESSAGE_CONTENT intents are enabled in the Discord Developer Portal).
   • discord.guild-id: Your Discord Server ID.
   • discord.license_key: Your valid License Key.
4. Restart your server or run /rolez reload in-game.

---

📜 Configuration (config.yml)

# Configuration file for RoleZ plugin
discord:
  token: "YOUR_DISCORD_BOT_TOKEN_HERE"
  guild-id: "YOUR_GUILD_ID_HERE"
  license_key: "YOUR_LICENSE_KEY_HERE"

# Map Discord Role IDs to Minecraft LuckPerms Group Names
rankSync:
  - groupName: "vip"
    DiscordRole: "123456789012345678"
  - groupName: "mod"
    DiscordRole: "987654321098765432"

# Role ID required for Discord admin commands
dcPermissions:
  forceUnlinkAccounts: "YOUR_ADMIN_ROLE_ID"

# Enable/Disable Unlink functionality
unlink:
  enabled: true

# Automatic Role Assignment upon Linking
linkedAccounts:
  DcRole: "ROLE_ID_HERE"      # Assigned in Discord on link (Leave empty to disable)
  McRole: "linked_player"     # Assigned in Minecraft on link (Leave empty to disable)

# Webhook Audit Logging
webhooks:
  syncLogs: "https://discord.com/api/webhooks/..."

---

🎮 Commands & Permissions

In-Game Commands

Command	Permission	Description
/link <code>	None (All Players)	Complete account linking using code from Discord
/unlink <code>	None (All Players)	Complete account unlinking using code from Discord
/ranksync	None (All Players)	Manually sync Discord roles to Minecraft ranks
/rankunsync	None (All Players)	Remove Minecraft ranks based on current Discord roles
/unlink admin force <mcusername>	rolez.admin.unlink	Force unlink a player's Minecraft and Discord account
/rolez help	None (All Players)	Show in-game help menu
/rolez reload	rolez.admin.reload	Reload config.yml and messages.yml

Discord Slash Commands

Command	Usage	Description
/link	/link username:<mcname>	Generate a 6-digit code to link your account
/unlink user	/unlink user	Generate an unlink verification code
/unlink force	/unlink force user:<@DiscordUser>	Force unlink a user (Requires Admin role)
/ranksync	/ranksync	Sync your Discord roles to Minecraft ranks
/rankunsync	/rankunsync	Unsync Minecraft ranks based on Discord roles
/mcuser get	/mcuser get user:<@DiscordUser>	Retrieve the Minecraft username linked to a Discord user
/help	/help	Show Discord interaction help menu

---

🧩 PlaceholderAPI Identifiers

Integrate RoleZ placeholders with TAB, Scoreboard, Chat, or Hologram plugins using %rolez_<placeholder>%.

Server & Global Placeholders

• %rolez_total_linked% — Total count of linked accounts in database.
• %rolez_total_online_linked% — Number of currently online linked players.
• %rolez_total_online_unlinked% — Number of currently online unlinked players.
• %rolez_link_percentage% — Percentage of online players who are linked.
• %rolez_guild_name% — Name of the connected Discord Guild.

Player-Specific Placeholders

• %rolez_linked% — Returns true or false.
• %rolez_link_status% — Returns Linked or Not Linked.
• %rolez_discord_id% — Linked Discord User ID.
• %rolez_discord_name% — Linked Discord Username.
• %rolez_discord_displayname% — Discord Server Display Name / Nickname.
• %rolez_synced_rank% — Primary synced rank group name.
• %rolez_synced_ranks% — Comma-separated list of all synced ranks.
• %rolez_synced_rank_count% — Number of synced ranks.
• %rolez_luckperms_prefix% — Player's LuckPerms prefix.
• %rolez_linked_dcrole% — Configured default Discord role name.
• %rolez_linked_mcrole% — Configured default Minecraft role name.

---

📄 License & Credits

Developed by FizzyStudio. All rights reserved.