A library to implement a leveling system into a discord bot. One of the most popular discord bots out there is MEE6 and its leveling system. This library provides ways to easily implement one for yourself. It uses SQLite (aiosqlite) to locally query things such as their XP, rank, and level. Various amounts of other methods and classes are also provided so you can access or remove contents from the database file.

Installing

You can install the latest PyPI version of the library by doing:

$ pip install discordLevelingSystem

Or the development version:

$ pip install git+https://github.com/Defxult/discordLevelingSystem

Showcase

showcase

How to import

from discordLevelingSystem import DiscordLevelingSystem, LevelUpAnnouncement, RoleAward

Intents

Intents are required for proper functionality

bot = commands.Bot(..., intents=discord.Intents(messages=True, guilds=True, members=True))

DiscordLevelingSystem

class DiscordLevelingSystem(rate=1, per=60.0, awards=None, **kwargs)

Parameters of the DiscordLevelingSystem constructor

rate (int) The amount of messages each member can send before the cooldown triggers
per (float) The amount of seconds each member has to wait before gaining more XP, aka the cooldown
awards (Optional[Dict[int, List[RoleAward]]]) The role given to a member when they reach a RoleAward level requirement

Kwargs of the DiscordLevelingSystem constructor

| Name | Type | Default Value | Info |------|------|---------------|----- | no_xp_roles | Sequence[int] | None | A sequence of role ID's. Any member with any of those roles will not gain XP when sending messages | no_xp_channels | Sequence[int] | None | A sequence of text channel ID's. Any member sending messages in any of those text channels will not gain XP | announce_level_up | bool | True | If True, level up messages will be sent when a member levels up | stack_awards | bool | True | If this is True, when the member levels up the assigned role award will be applied. If False, the previous role award will be removed and the level up assigned role will also be applied | level_up_announcement | Union[LevelUpAnnouncement, Sequence[LevelUpAnnouncement]] | LevelUpAnnouncement() | The message that is sent when someone levels up. If this is a sequence of LevelUpAnnouncement, one is selected at random |bot | Union[AutoShardedBot, Bot] | None | Your bot instance variable. Used only if you'd like to use the on_dls_level_up event

Attributes

no_xp_roles
no_xp_channels
announce_level_up
stack_awards
level_up_announcement
bot
rate (int) Read only property from the constructor
per (float) Read only property from the constructor
database_file_path (str) Read only property
active (bool) Enable/disable the leveling system. If False, nobody can gain XP when sending messages unless this is set back to True

NOTE: All attributes can be set during initialization

Initial Setup

When setting up the leveling system, a database file needs to be created in order for the library to function.

Associated static method
- DiscordLevelingSystem.create_database_file(path: str)

The above static method is used to create the database file for you in the path you specify. This method only needs to be called once. Example:

DiscordLevelingSystem.create_database_file(r'C:\Users\Defxult\Documents')

Once created, there is no need to ever run that method again unless you want to create a new database file from scratch. Now that you have the database file, you can use the leveling system.

Connecting to the Database

Associated method
- DiscordLevelingSystem.connect_to_database_file(path: str)

Since the database file has already been created, all you need to do is connect to it.

NOTE: When connecting to the database file, the event loop must not be running

<div align="left"><sub>EXAMPLE</sub></div>

from discord.ext import commands
from discordLevelingSystem import DiscordLevelingSystem

bot = commands.Bot(...)
lvl = DiscordLevelingSystem()
lvl.connect_to_database_file(r'C:\Users\Defxult\Documents\DiscordLevelingSystem.db')

bot.run(...)

RoleAward

class RoleAward(role_id: int, level_requirement: int, role_name=None)

You can assign roles to the system so when someone levels up to a certain level, they are given that role. RoleAward is how that is accomplished.

Parameters of the RoleAward constructor

role_id (int) ID of the role that is to be awarded.
level_requirement (int) What level is required for a member to be awarded the role.
role_name (Optional[str]) A name you can set for the award. Nothing is done with this value, it is used for visual identification purposes only.

Attributes

role_id
level_requirement
role_name
mention (str) The discord role mention string

When creating role awards, all role IDs and level requirements must be unique. Level requirements must also be in ascending order. It is also possible to assign different role awards for different guilds. If you don't want any role awards, set the awards parameter to None. When setting awards, it accepts a dict where the keys are guild IDs and the values are a list of RoleAward

<div align="left"><sub>EXAMPLE</sub></div>

from discordLevelingSystem import DiscordLevelingSystem, RoleAward

johns_server = 587937522043060224
janes_server = 850809412011950121

my_awards = {
    johns_server : [
        RoleAward(role_id=831672678586777601, level_requirement=1, role_name='Rookie'),
        RoleAward(role_id=831672730583171073, level_requirement=2, role_name='Associate'),
        RoleAward(role_id=831672814419050526, level_requirement=3, role_name='Legend')
    ],
    janes_server : [
        RoleAward(role_id=851400453904400385, level_requirement=1, role_name='Silver'),
        RoleAward(role_id=851379776111116329, level_requirement=2, role_name='Gold'),
        RoleAward(role_id=851959077071880202, level_requirement=3, role_name='Diamond')
    ]
}

lvl = DiscordLevelingSystem(..., awards=my_awards)

LevelUpAnnouncement

class LevelUpAnnouncement(message=default_message, level_up_channel_ids=None, allowed_mentions=default_mentions, tts=False, delete_after=None)

Level up announcements are for when you want to implement your own level up messages. It provides access to who leveled up, their rank, level and much more. It also uses some of discord.py's kwargs from its Messageable.send() such as allowed_mentions, tts, and delete_after to give you more control over the sent message.

Parameters of the LevelUpAnnouncement constructor

message (Union[str, discord.Embed]) The message that is sent when someone levels up. Defaults to "<mention>, you are now **level <level>!**"
level_up_channel_ids (Optional[Sequence[int]]) The text channel IDs where all level up messages will be sent for each server. If None, the level up message will be sent in the channel where they sent the message (example below).
allowed_mentions (discord.AllowedMentions) Used to determine who can be pinged in the level up message. Defaults to discord.AllowedMentions(everyone=False, users=True, roles=False, replied_user=False)
tts (bool) When the level up message is sent, have discord read the level up message aloud.
delete_after (Optional[float]) Delete the level up message after an x amount of seconds.

Class Attributes

The LevelUpAnnouncement class provides a set of markdown attributes for you to use so you can access certain information in a level up message.

LevelUpAnnouncement.TOTAL_XP The members current total XP amount
LevelUpAnnouncement.LEVEL The members current level
LevelUpAnnouncement.RANK The members current rank

The below markdown attributes takes the information from a discord.Member object so you can access member information in the level up message.

LevelUpAnnouncement.Member.avatar_url
LevelUpAnnouncement.Member.banner_url
LevelUpAnnouncement.Member.created_at
LevelUpAnnouncement.Member.default_avatar_url
LevelUpAnnouncement.Member.discriminator
LevelUpAnnouncement.Member.display_avatar_url
LevelUpAnnouncement.Member.display_name
LevelUpAnnouncement.Member.id
LevelUpAnnouncement.Member.joined_at
LevelUpAnnouncement.Member.mention
LevelUpAnnouncement.Member.name
LevelUpAnnouncement.Member.nick
LevelUpAnnouncement.Member.Guild.icon_url
LevelUpAnnouncement.Member.Guild.id
LevelUpAnnouncement.Member.Guild.name

<div align="left"><sub>EXAMPLE</sub></div>

from discordLevelingSystem import DiscordLevelingSystem, LevelUpAnnouncement

embed = discord.Embed()
embed.set_author(name=LevelUpAnnouncement.Member.name, icon_url=LevelUpAnnouncement.Member.avatar_url)
embed.description = f'Congrats {LevelUpAnnouncement.Member.mention}! You are now level {LevelUpAnnouncement.LEVEL} 😎'

announcement = LevelUpAnnouncement(embed)

lvl = DiscordLevelingSystem(..., level_up_announcement=announcement)

# NOTE: You can have multiple level up announcements by setting the parameter to a sequence of LevelUpAnnouncement
lvl = DiscordLevelingSystem(..., level_up_announcement=[announcement_1, announcement_2, ...])

When it comes to level_up_channel_ids, you c

DiscordLevelingSystem

Install / Use

README

Installing

Showcase

How to import

Intents

DiscordLevelingSystem

Parameters of the DiscordLevelingSystem constructor

Kwargs of the DiscordLevelingSystem constructor

Attributes

Initial Setup

Connecting to the Database

RoleAward

Parameters of the RoleAward constructor

Attributes

LevelUpAnnouncement

Parameters of the LevelUpAnnouncement constructor

Class Attributes