Adding a commnad

Getting started

Want to add a command to the project? This is the best place to start!

The bot is written using a package called discord-py, you can find its documentation here, A few changes have been made however and that is what we will be covering here.

Firstly to create a command lets look at a quick start example

# /bot/commands/ping.py
from bot.config import Config, Embed
from bot.base import Command

class cmd(Command):
    """ A discord command instance. """

    name = "ping"
    usage = "ping"
    description = "Check the current latency of the bot."

    async def execute(self, arguments, message) -> None:
        embed = Embed(title="Hello world!", description="This is a test embed")
        await message.channel.send("Im alive!!", embed=embed)

In this example we create a class with the name ping, to execute the command we will use <prefix>ping

The usage attribute describes how to use the command, this is useful info for our help system and argument parser. A element wrapped in <> is required while [] is optional.

To specify the datatype we can add a colon, eg.

• [user:member] Will return the member running the command if nothing is specified
• <count:int> Converts the result to an integer
• <multiplier:float> Converts to a float
• <frfr:bool> Converts it to a boolean (true/false)

Of cause all of these work with both optional and required arguments, only the bits after : counts as the typecasting, default type is str

When the user gives an argument it is possible to wrap it in quotes to input multiple words.

If you want to just catch all the following arguments in a joined one, eg. v!test save This is multiple words in a single arg you can instead use the * operator, how the usage string would look for this could be test <option> [*message], here we define an optional message argument of undefined length.

In your command you have access to self.bot, self.manager, self.db and self.logger, to work with the database we can look at the following example

Accessing the database

The database can be found in the file bot/sql.py to use it in your app you can access self.db, current supported methods are

        await self.db.raw_exec_commit(
            "INSERT INTO levels(exp, level, user_id) VALUES (?,?,?)",
            (exp, lvl, arguments[0]),
        )

        result = await self.db.raw_exec_select(
            f"SELECT exp, level FROM levels WHERE user_id = '?'",
            (user.id,)
        )

After porting to using MySQL both ? and %s are supported, ? will be replaced with %s on runtime.

raw_exec_commit takes in the sql statment and values of that, it will automatically connect to the database and close it as well, the _commit will automatically commit your statement and _select will return a list of tuples

Simply we access the self.db attribute to get our data.

Embeds

In the project we changed a bit how embeds work, we have a default format that of cause can be overwritten if necessary. You can use all the default attributes and methods from the discord py documentation.

As well as this we implemented a set color method to set the default color, by default embed colors are green. You need to use this to set the color of the embed, here is an example.

from bot.config import Config, Embed

embed = Embed(title="Hello world!")
embed.set_color("red")

The embed object will now be red. Supported colors currently are:

The v1rbox embeds follow the same template to have a more consistent look and experience for the end user.