Auto Level
Plugin name: autolevel
The AutoLevel plugin provides a guild leveling system that can reward roles to members for participating in text and voice channels.
The HepBoat autoleveling system also provides a means to have multiple guild leveling systems running at the same time, since each category can be set up with its own levelling system.
Commands
Arguments in {} are required. Arguments in [] are optional.
| Name | Description | Default Level | Usage |
|---|---|---|---|
!level OR !rank | Shows the calling user's current points and levels in the guild. This level is not calculated based on the assigned levels in the configuration. | Default | !level OR !rank |
!top [index] | Shows the guild's top 10 ranked users overall or in the given index in addition to the calling user's current ranking. | Default | !top |
!alevel show [user] OR !alevel ls [user] | Shows all the indexes that the calling or given user is currently collecting points in. | Moderator | !alevel show 76685590585671680 OR !alevel ls 76685590585671680 |
!alevel level [rank] OR !alevel rank [rank] | Shows how many points are required to reach a specific rank. This rank is not calculated based on the assigned levels in the configuration. | Moderator | !alevel level 6 |
!alevel give {user} {points} [index] OR !alevel add {user} {points} [index] | Adds the given number of points to the given user in the given index. If no index is specified, it will use the default base configuration 0:0 index. | Administrator | !alevel give 76685590585671680 10000 0:0 |
!alevel take {user} {points/all} [index] OR !alevel rm {user} {points/all} [index] | Removes the given number of points to the given user in the given index. If no index is specified, it will use the default base configuration 0:0 index. | Administrator | !alevel take 76685590585671680 10000 0:0 |
!alevel reset [index] | Deletes all guild data for the given index. If no index is specified, it will use the default base configuration 0:0 index. | Administrator | !alevel reset 579304983896391681:0 |
!alevel import {type} {guild_id} [index] | Imports Mee6 or Tatsumaki points into the current guild in the given index. If no index is specified, it will use the default base configuration 0:0 index. Available types: Mee6, Tatsumaki | Global Administrator | !alevel import tatsumaki 76685590585671680 0:0 |
info
The import command is only available to Global Admins. Please join our support guild to ask for assistance.
Configuration Options
Levelling indexes are assigned based on base and category configurations.
A default base configuration uses the index 0:0. A base configuration that enables include_roles and not include_channels uses the index 0:role. A base configuration that enables include_channels uses the index 0:channel.
Similarly, a default category configuration uses the index {category_id}:0. A category configuration that enables include_roles and not include_channels uses the index {category_id}:role. A category configuration that enables include_channels uses the index {category_id}:channel.
| Option | Description | Type | Default |
|---|---|---|---|
| include_roles | A list of whitelisted roles. If empty, all roles are included by default. | list(snowflake) | empty |
| exclude_roles | A list of excluded roles. | list(snowflake) | empty |
| include_channels | A list of whitelisted channels. If empty, all channels are included by default. If set, only whitelisted channels (text or voice) will be counted. | list(snowflake) | empty |
| exclude_channels | A list of excluded channels. | list(snowflake) | empty |
| include_voice | A list of whitelisted voice channels. Voice channels need to be explicitly whitelisted, or they will not be counted. | list(snowflake) | empty |
| include_voice_category | A list of whitelisted categories with child voice channels. Voice channels need to be explicitly whitelisted, or they will not be counted. | list(snowflake) | empty |
| include_category | A list of whitelisted categories. | list(snowflake) | empty |
| exclude_category | A list of excluded categories. | list(snowflake) | empty |
| multiplier | A multiplier configuration that decides how many points are awarded for each message or period of voice activity. A multiplier must be manually set or the levelling system will not award any points. | dict | None |
| multiplier_roles | A mapping of roles to an additional multiplier. Format of values is roleid: 3 | dict | empty |
| weight | A weight configuration that will randomize the multiplier point value. | dict | None |
| levels | A mapping of number of points to a role ID that will be assigned. | dict | None |
| keep_previous | Whether or not to keep previous level roles when a new level is reached. | bool | False |
| announce_msg | Message to post when a user reaches a new level role. | str | None |
| announce_chan | The channel the announce message will be posted to | snowflake | None |
| announce_dm | Whether or not to DM the announce_msg to the user when they reach a new level role. | bool | False |
| seconds_per_point | Number of seconds before more points are awarded to a user. | int | 60 |
| category | A mapping of category IDs to category autolevel configurations. | dict | None |
| level_footer_url | An image URL for the level footer. If unset, it will default to the guild icon. | str | None |
info
Blacklists are respected over whitelists in a conflict.
Multiplier Configuration
| Option | Description | Type | Default |
|---|---|---|---|
| message | Number of points to assign per message. | int | 25 |
| voice | Number of points to assign per seconds_per_point period. | int | 25 |
info
If no multiplier configuration is set in a category configuration, it will inherit values from the parent base configuration.
Weight Configuration
| Option | Description | Type | Default |
|---|---|---|---|
| message | +/- the number of points to the multiplier message value. | int | 5 |
| voice | +/- the number of points to the multiplier voice value. | int | 5 |
| seconds | +/- the number of seconds to the seconds_per_point value. | int | 15 |
info
If no weight configuration is set in a category configuration, it will inherit values from the parent base configuration.
Category AutoLevel Configuration
| Option | Description | Type | Default |
|---|---|---|---|
| include_roles | A list of whitelisted roles. If empty, all roles are included by default. | list(snowflake) | empty |
| exclude_roles | A list of excluded roles. | list(snowflake) | empty |
| include_channels | A list of whitelisted channels. If empty, all channels are included by default. | list(snowflake) | empty |
| exclude_channels | A list of excluded channels. | list(snowflake) | empty |
| include_voice | A list of whitelisted voice channels. Voice channels need to be explicitly whitelisted, or they will not be counted. | list(snowflake) | empty |
| include_voice_category | A list of whitelisted categories with child voice channels. Voice channels need to be explicitly whitelisted, or they will not be counted. | list(snowflake) | empty |
| multiplier | A multiplier configuration that decides how many points are awarded for each message or period of voice activity. A multiplier must be manually set or the levelling system will not award any points. | dict | None |
| multiplier_roles | A mapping of roles to an additional multiplier. Format of values is roleid: 3 | dict | empty |
| weight | A weight configuration that will randomize the multiplier point value. | dict | None |
| levels | A mapping of number of points to a role ID that will be assigned. | dict | None |
| keep_previous | Whether or not to keep previous level roles when a new level is reached. | bool | False |
| announce_msg | Message to post when a user reaches a new level role. | str | None |
| announce_chan | The channel the announce message will be posted to | snowflake | None |
| announce_dm | Whether or not to DM the announce_msg to the user when they reach a new level role. | bool | False |
| seconds_per_point | Number of seconds before more points are awarded to a user. | int | 60 |
announce_msg Message Tokens
The following tokens can be used in the announce_msg contents to dynamically generate content when a new role is assigned.
| Token | Description |
|---|---|
{user} | Will mention the awarded user. |
{server} | Will include the server name. |
{channel} | Will mention the current channel. |
{new_role} | Will mention the newly assigned role. |
{r<snowflake>} | Will mention the specified role. |
{c<snowflake>} | Will mention the specified channel. |
{u<snowflake>} | Will mention the specified user. |
Configuration Example
plugins:
autolevel: # base configuration uses index 0:0, no voice channels enabled.
seconds_per_point: 1
keep_previous: true
multiplier:
message: 8
levels:
1000: 536728628680196126
2000: 536728691795951619
3000: 536728730714898442
category:
9843950989345098345: # uses index 9843950989345098345:role
include_roles:
- 3245098734095345980340
- 239045823094823094823
include_voice_category: # will give points for voice channels in this category.
- 9843950989345098345
multiplier:
message: 12
voice: 25
multiplier_roles:
536728691795951619: 2
weight:
message: 2
voice: 10
seconds: 4
levels:
500: 2385947349805897345
1500: 3245987345987345987
3000: 34534509834509340598
10000: 324590834509853450985
keep_previous: true
seconds_per_point: 15
announce_msg: '{user} has leveled up!! yeet!'
announce_chan: 3454908448974987444
2394823904823487897: # uses index 2394823904823487897:0
exclude_channels:
- 238945723472384234987
- 2354987324598734598755
multiplier:
message: 100
levels:
10000: 3458973458937534598
25000: 23458974328974234984
50000: 3459083450983458738
seconds_per_point: 30
keep_previous: true