🌟 Custom Roles Bot — Advanced Role Personalization for Discord Servers

Custom Roles Bot is a powerful and automated Discord bot that gives your server members the ability to create, manage, and personalize their own roles — including custom names, solid or gradient colors, role icons, and even holographic effects. Designed for communities that want user flair, cleaner role management, and better self-expression.

🚀 Key Features

🧩 Role Personalization

Members can create a unique personal role with:

• Custom names (/role name)
• Solid colors or named colors (/role colour_solid)
• Gradient color effects using two colors (/role colour_gradient)
• Holographic effects with multi-tone shimmer (/role colour_holographic)
• Custom role icons, including emojis or image URLs (/role icon)

🧹 Automatic Cleanup

• If a role starts with a special prefix and no members have it, the bot deletes it.
• If the only member with a custom role loses the "required role", the bot auto-deletes their custom role.
• Helps prevent role clutter and keeps your server clean.

🔐 Secure & Permission-Aware

• Only users with a required role (defined via /setup) can create personal roles.
• Bot ensures its own role is above the editable role position to function properly.
• Role creation is limited to servers with fewer than 250 roles to prevent hitting Discord's max limit.
• All actions are permission-checked to avoid errors or misuse.

⚙️ Admin Setup (/setup)

Admins can configure:

• The required role that users must have to manage custom roles.
• The role position below which all custom roles should be created.
• A log channel to receive error messages when role operations fail (e.g. missing permissions).

🎨 Color Support

• Accepts hex codes, Discord color names (red, blue, lime, etc.), and fallback to color IDs.
• Automatically translates friendly color names into Discord-compatible color integers.

🖼 Emoji & Icon Support

• Members can use:

  • Unicode emojis (🔥, 😎)
  • Custom Discord emojis (<:name:id>)
  • Animated emojis (<a:name:id>)
  • Direct image URLs (https://...)

• Bot fetches and applies the emoji/icon appropriately to the role.

🔧 How It Works

1. Admin runs /setup to configure the bot for the server.

2. Users with the required role run /role name to generate a personal role.

3. Users can further customize their role using:

   • /role colour_solid
   • /role colour_gradient
   • /role colour_holographic
   • /role icon

4. Bot ensures roles are positioned correctly and enforces clean-up when necessary.

📁 Configuration Storage

• All server-specific configs are stored in custom_roles.json

• Keeps track of:

  • Guild ID
  • Required role ID
  • Target role position
  • Logging channel ID

🧠 Technical Highlights

• Built using py-cord for full slash command support.
• Uses manual REST API calls to Discord’s endpoints for features like gradients and holographic colors, which aren't fully exposed in the library yet.
• Local JSON file storage (no database needed).
• Modular with two main Cogs: Setup and RoleCommands.

⚠️ Notes & Limitations

• Discord limits servers to 250 roles — this bot checks and prevents creating more when full.
• Requires Manage Roles and Send Messages permissions.
• Bot role must be higher than all custom roles it tries to edit or create.
• Role icons require your server to be boosted to Level 2.

📢 Ideal Use Cases

• VIP systems (members with VIP role can create their own flair)
• Customizable user flair in gaming or community servers
• Boosted servers wanting users to personalize their roles
• Cleaner role system with automated cleanup logic

📝 Example Commands

/setup             # Admin config
/role name         # Set your role name
/role colour_solid # Set role color
/role colour_gradient # Set gradient color
/role colour_holographic # Fancy shimmer
/role icon         # Add emoji/icon to role

🔒 Privacy and Security

• No message content is stored or logged.
• Only config data is saved locally.
• All actions respect Discord permissions and API rate limits.

🧠 Summary

Custom Roles Bot gives your members more expression, automates cleanup, and helps your server stand out with stylish, personalized roles — all in a safe, permission-aware, and scalable system.