Discord Permission Sync for FiveM

Monolith DPS is an advanced integration between discord roles and permissions on your FiveM Server with the ESX Framework.

Features

• Automatic Role Sync: Seamlessly syncs Discord roles to ESX groups
• Smart Queue System: Handles rate limits with intelligent request queuing
• Rate Limit Protection: Built-in safeguards against Discord API rate limiting
• Highly Configurable: Extensive configuration options for fine-tuning
• Debug Mode: Detailed logging for troubleshooting (production-friendly)
• Performance Optimized: Efficient bulk operations with configurable batching
• Error Resilience: Comprehensive error handling with fallback options
• Priority System: Role hierarchy based on configuration order

Requirements

• FiveM Server with ESX framework
• Discord Bot with proper permissions
• Discord Guild where roles are managed

Installation

1. Download or clone this repository
2. Extract the files to your resources folder
3. Add ensure monolith-dps to your server.cfg
4. Configure the config.lua file (see Configuration section)
5. Restart your server

Configuration

Basic Setup

Edit config.lua and configure the following essential settings:

Config = {
  -- Discord Bot Configuration
  botToken = "YOUR_BOT_TOKEN",              -- Your Discord bot token
  guildId = "YOUR_GUILD_ID",                -- Your Discord server ID

  -- Role Configuration (ORDER MATTERS!)
  roles = {
    { id = "ROLE_ID_1", name = "superadmin" }, -- Highest priority
    { id = "ROLE_ID_2", name = "admin" },      -- Medium priority
    { id = "ROLE_ID_3", name = "moderator" },  -- Lower priority
    -- Add more roles as needed
  },
}

Discord Bot Setup

1. Create a Discord Application:

   • Go to Discord Developer Portal
   • Click “New Application” and give it a name
   • Go to “Bot” section and click “Add Bot”

2. Get Your Bot Token:

   • In the Bot section, click “Copy” under Token
   • Paste this token in config.lua as botToken

3. Set Bot Permissions:

   • Your bot needs View Server Members permission
   • Invite the bot to your Discord server with this permission

4. Get Guild ID:

   • Enable Developer Mode in Discord
   • Right-click your server → “Copy Server ID”
   • Paste this in config.lua as guildId

5. Get Role IDs:

   • Right-click any role in your Discord server
   • Click “Copy Role ID”
   • Add roles to the roles table in config.lua

Role Priority System

IMPORTANT: Role priority is determined by the ORDER in the roles table!

roles = {
  { id = "123456789", name = "superadmin" }, -- 🥇 HIGHEST PRIORITY
  { id = "987654321", name = "admin" },      -- 🥈 Medium priority
  { id = "456789123", name = "user" },       -- 🥉 Lowest priority
}

If a player has multiple configured Discord roles, they will receive the first matching role from the list.

Advanced Configuration

Config = {
  -- Debug Settings
  debugMode = false,                        -- Enable detailed logging

  -- Rate Limiting & Queue Settings
  apiCooldown = 1000,                       -- Delay between API calls (ms)
  queueProcessDelay = 100,                  -- Queue processing delay (ms)
  rateLimitRetryDelay = 5000,               -- Rate limit retry delay (ms)

  -- Bulk Operation Settings
  bulkSyncBatchSize = 5,                    -- Players per batch
  bulkSyncDelay = 1000,                     -- Delay between batches (ms)

  -- Fallback Settings
  defaultRole = "user",                     -- Default role assignment
  fallbackOnError = true,                   -- Use default role on errors
}

Commands

Console Commands (Server Console Only)

refreshpermissions

• Description: Manually refresh permissions for all online players
• Usage: Type in server console to force a permission sync
• Note: Clears the request queue and processes all players fresh

Debug Mode

Enable debug mode for detailed logging:

debugMode = true

Debug Mode Shows:

• Individual player role assignments
• Queue status and processing details
• API request/response information
• Detailed error messages

Production Mode (debugMode = false):

• Clean console output
• Only essential error messages
• No per-player spam

Troubleshooting

Common Issues

“Bot token not configured”

Solution: Make sure you’ve replaced YOUR_BOT_TOKEN with your actual Discord bot token.

“Bot lacks permissions”

Solution: Ensure your Discord bot has View Server Members permission in your Discord server.

“User not found in Discord guild”

Solution: Player isn’t in your Discord server or has their Discord account disconnected from FiveM.

“Rate limit exceeded”

Solution: The queue system will automatically handle this. If persistent, increase apiCooldown value.

Debug Steps

1. Enable Debug Mode:

   debugMode = true
   

2. Check Console Output: Look for colored error messages:

   • Red: Critical errors
   • Yellow: Warnings
   • Green: Success messages
   • Gray: Debug information

3. Verify Configuration: Restart the resource and check for configuration errors

4. Test Manual Refresh: Use refreshpermissions command in console

Performance Tuning

If you experience issues with many players:

-- Reduce batch sizes
bulkSyncBatchSize = 3,
manualRefreshBatchSize = 2,

-- Increase delays
apiCooldown = 2000,
bulkSyncDelay = 2000,

Security Notes

• NEVER SHARE your Discord bot token
• Store your bot token securely
• Use minimal required Discord permissions

Update Notes

From Basic Version

• Caching removed for real-time accuracy
• Queue system added for rate limit handling
• Debug mode added for production-friendly logging
• All settings moved to config file
• Enhanced error handling and resilience

Support

If you encounter issues:

1. Check this README for common solutions
2. Enable debug mode and check console output
3. Verify your Discord bot setup and permissions
4. Test with the manual refresh command

Made with for the FiveM community

Download