Adding and Editing Commands

Before continuing, you should have at least some knowledge of python, as adding commands does require writing code.

You may also want to have a look at the discord.py documentation

Adding new commands/features

gBot has been coded to make adding new features relatively easy. New commands go into .py files in the cogs folder. While not strictly necessary, it is recommended you keep each command in its own file, as this lets the help command that comes with gBot list the commands properly.

Here's an example command file:

## Initialization
import discord
from common import log, config, embedMessage
from discord.ext import commands

## Class setup
class badd(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

        ## Help stuff
        self.hidden = False
        self.description = "Adds numbers together but is overly finicky about it."
        self.usage = f"""
        {config.cfg['options']['prefix']}add <first number> <second number>
        """

        ## Config stuff
        self.firstNumber = config.cfg['settings']['exampleCommand']['firstNumber']
        self.favNumber = config.cfg['settings']['exampleCommand']['favNumber']

    ## Command defining
    @commands.command()
    @commands.has_guild_permissions(embed_links=True, attach_files=True)
    async def badd(self, ctx, arg1: int, arg2: int):
        if arg1 == 9 and arg2 == 10:
            embed = embedMessage.embed(
                title = 'whas nahn plus tehn?',
                description = 'twenny wan',
                color = embedMessage.defaultColor
            )
            await ctx.send(embed=embed)
            return
        if arg1 != self.firstNumber:
            embed = embedMessage.embed(
                title = 'ERROR',
                description = f'Sorry, the first number must be {self.firstNumber}!',
                color = embedMessage.errorColor
            )
            await ctx.send(embed=embed)
            return
        ans = arg1 + arg2
        if ans == self.favNumber:
            embed = embedMessage.embed(
                title = 'WOW!',
                description = f'The answer is {self.favNumber}, my favorite number!',
                color = discord.Color.from_rgb(255, 215, 0)
            )
            await ctx.send(embed=embed)
            return
        embed = embedMessage.embed(
            title = 'SUCCESS',
            description = f'The answer is {ans}.',
            color = embedMessage.defaultColor
        )
        await ctx.send(embed=embed)

## Allow use of cog class by main bot instance
def setup(bot):
    bot.add_cog(badd(bot))

...a bit of a wall of text, so let's break it down piece by piece

## Initialization
import discord
from common import config, log, embedMessage
from discord.ext import commands

Starting off easy, this is where you should put your imports. In this case, we are importing discord.py and its command module, which lets us interface with the Discord API easily, and makes command creation much simpler. We are also importing some things from the common folder:

• log: You should always have this, makes logging work.
• config: Allows us to access config.yaml for easy user customization.
• embedMessage: Helps make embeds easier to use.

## Class setup
class badd(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

This defines what the class is called (and unless otherwise specified, how it shows up in the help command) and lets us refer to the bot later in the file as "self.bot"

## Help stuff
self.hidden = False
self.description = "Adds numbers together but is overly finicky about it."
self.usage = f"""
{config.cfg['options']['prefix']}add <first number> <second number>
"""

This section is where you should put things that the help command will use to display the command in the help menu. The options here are:

• self.hidden: If true, this command will NOT show up in help
• self.qualified_name: What the command is called in help
• self.description: A short description that appears with the commands name in help
• self.usage: The usage and syntax of the command. Shows up when you do help <command>

## Config stuff
self.firstNumber = config.cfg['settings']['exampleCommand']['firstNumber']
self.favNumber = config.cfg['settings']['exampleCommand']['favNumber']

This section is just putting config settings into variables, for easy access later.

## Command defining
@commands.command()
@commands.has_guild_permissions(embed_links=True, attach_files=True)
async def badd(self, ctx, arg1: int, arg2: int):

This part simply defines some stuff about the command.

• @commands.command(): This means that this is a command, and not something like a listener.
• @commands.has_guild_permissions: This is a decorator that checks if the user running the command has the permissions needed to use the command. List of valid permissions here.
• async def badd: This is where you put the word used to invoke the function, in this case that would be badd.
• (self, ctx, arg1: int, arg2: int): This is defining the commands input arguments, if any.
  • self: Required, must be first. By being in a class, the command is automatically given the class as the first argument.
  • ctx: Required, must be second. It means context, and allows easy referring to attributes of the message containing the command.
  • arg1: int: The first argument given by the user will be stored in the variable arg1 as an integer. arg2 is exactly the same.

if arg1 == 9 and arg2 == 10:
    embed = embedMessage.embed(
            title = 'whas nahn plus tehn?',
            description = 'twenny wan',
            color = embedMessage.defaultColor
    )
    await ctx.send(embed=embed)
    return

This if statement checks to see if arg1 is 9, and arg2 is 10. If both are, it outputs an embed containing a special message. Embed parameters are:

• title: The text shown at the top of the embed.
• description: The text in the embed, shown before the body text.
• sections: A list of different sections to be in the embed.
• body: A list of entries, they should be separated by <hr>, follows the same order as sections.
• color or colour: A discord.Colour object that overrides the default color, which is the vertical bar on the left of the embed.
• url: A webpage to link to.
• thumbnail: A boolean. If true, displays the image defined in config.yaml.
• footer: Some text to put at the bottom of the embed.

if arg1 != self.firstNumber:
    embed = embedMessage.embed(
            title = 'ERROR',
            description = f'Sorry, the first number must be {self.firstNumber}!',
            color = embedMessage.errorColor
    )
    await ctx.send(embed=embed)
    return

This if statement checks if the first argument is the same as firstNumber, which is defined in config.yaml. If it isn't, it outputs an error telling the user why it refuses to add the 2 given numbers.

ans = arg1 + arg2
if ans == self.favNumber:
    embed = embedMessage.embed(
            title = 'WOW!',
            description = f'The answer is {self.favNumber}, my favorite number!',
            color = discord.Color.from_rgb(255, 215, 0)
    )
    await ctx.send(embed=embed)
    return
embed = embedMessage.embed(
    title = 'SUCCESS',
    description = f'The answer is {ans}.',
    color = embedMessage.defaultColor
)
await ctx.send(embed=embed)

This section defines ans as arg1 plus arg2, checks if ans is the same as favNumber (defined in the config), and if it is, outputs an embed with a special color, stating the answer as its favorite number. If ans is not the same as favNumber, it simply outputs the answer in an embed.

## Allow use of cog class by main bot instance
def setup(bot):
    bot.add_cog(badd(bot))

The last part, this finalizes the cog, allowing it to be used by the bot.

This was just an example command. You can look at the other default cogs to see how some more useful commands and features work, but they don't have wiki pages explaining how they work in extreme detail, so you're on your own if you want to reverse-engineer them.

Editing commands is much simpler than making a new one, it simply involves tweaking things that aren't set up as configurable in config.yaml within the cog file itself. Depending on what you are editing, you might be able to do it even without experience with python, though I would still recommend you have some before doing so.