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