Plugins
Roles
The roles plugin provides utilities for managing roles in your server. It can give roles when members join and let members choose their own roles from reactions, buttons, or select menus.
# Join Roles
Join roles may let members bypass Rules Screening when it is enabled in your server. Do not use join roles in a server that relies on Rules Screening.
If you want members to choose a role to access the server, use a managed role group with a button or select menu instead. Otherwise, use Discord's Rules Screening on its own.
Join roles are roles given to people when they join. You can select up to two that will be given to new members when they join.
# Auto Roles
Auto roles are roles given to people when they react to a message with a set reaction, click a button or select a role from a dropdown.
# Role Groups
Atlas groups auto roles into role groups. A single role group corresponds to one or more messages in Discord. For managed role groups, they always correspond to a single message in Discord. The group content is the message content, which is disabled for unmanaged groups. Tags are supported in the role groups content.
# Managed Role Groups
Managed role groups are synced in the background. Changes to the content or list of roles may take up to a minute to be reflected in Discord. Removing a role will stop it being handed out immediately.
Managed role groups are automatically created by the bot and are updated when you update the role group.
# Unmanaged Role Groups
Unmanaged role groups are intended for an existing reaction-role message that Atlas does not own. The dashboard exposes this through the Managed toggle. Most servers should leave it enabled.
Unmanaged role groups are created by you. You must enter a message ID and select the channel the message is in, and Atlas will manage reactions on the message and give people roles when they react to the message.
Because Atlas cannot update unmanaged reaction groups, the content for a group is ignored. This also restricts the group to using only emoji reactions, other group types like buttons or select menus require the bot to update the message.
# Conditional Scripts
The conditional script part of each role is a small script that will determine whether the user reacting will be given that role. This script can return true, false or a message. If a message is returned, it is shown to the user. See Scripts for the basics.
For example, a script such as
{if;{user.roles};includes;BOOST_ROLE_ID;true;You need to be boosting the server to do that!}
would only allow people with the boost role to get that role. If the user does not have the role, it tells them You need to be boosting the server to do that!.
Expensive tags are disabled in conditional scripts, tags like {user.addRole} and {fetch} will throw an error.
# Role Labels
Labels can be configured per role and will be used in place of the role name for buttons or select menu groups. Without a label, the role name will be used.
# Role Options
- Description is shown for a role in a select menu.
- Conditional Script decides whether a member can receive the role. It may return
true,false, or a message to show to the user. - Sticky gives the role back when a member leaves and later rejoins the server.
- Permanent prevents a member from removing the role through the role group. Staff can still manage the role.
- Inverse makes selecting the entry remove the role instead of adding it.
The role limit belongs to the group, not an individual role. It is the maximum number of group roles a member may hold. 0 means no limit.
Role groups can send success and error messages by direct message. DMs can fail when a member has them closed.
Atlas must be above every role it should manage. See Advanced Settings before enabling privileged roles.