Skip to main content

Cogs

Cogs, often known as modules or extensions, are used to organize commands into groups. This is useful for grouping commands that have the same general idea (such as moderation commands). This also helps to avoid making your bot's files messy and cluttered.

Getting Started​

First, you'll need to create a folder to store your cogs, e.g. cogs/.

Then, create a file inside the folder, e.g. cogs/greetings.py. By convention, the file name should be the same as the name of the cog or module.

We can then create the cog.

./cogs/greetings.py
import discord
from discord.ext import commands

class Greetings(commands.Cog): # create a class for our cog that inherits from commands.Cog
    # this class is used to create a cog, which is a module that can be added to the bot

    def __init__(self, bot): # this is a special method that is called when the cog is loaded
        self.bot = bot

    @commands.command() # creates a prefixed command
    async def hello(self, ctx): # all methods now must have both self and ctx parameters
        await ctx.send('Hello!')

    @discord.slash_command() # we can also add application commands
    async def goodbye(self, ctx):
        await ctx.respond('Goodbye!')

    @discord.user_command()
    async def greet(self, ctx, member: discord.Member):
        await ctx.respond(f'{ctx.author.mention} says hello to {member.mention}!')

    math = discord.SlashCommandGroup("math", "Spooky math stuff") # create a Slash Command Group called "math"
    advanced_math = math.create_subgroup(
        "advanced",
        "super hard math commands!"
    )

    @math.command()
    async def add(self, a: int, b: int):
        c = a + b
        await ctx.respond(f"{a} + {b} is {c}.")
    
    @advanced_math.command()
    async def midpoint(self, x1: float, y1: float, x2: float, y2: float):
        mid_x = (x1 + x2)/2
        mid_y = (y1 + y2)/2
        await ctx.respond(f"The midpoint between those coordinates is ({mid_x}, {mid_y}).")

    @commands.Cog.listener() # we can add event listeners to our cog
    async def on_member_join(self, member): # this is called when a member joins the server
    # you must enable the proper intents
    # to access this event.
    # See the Popular-Topics/Intents page for more info
        await member.send('Welcome to the server!')

def setup(bot): # this is called by Pycord to setup the cog
    bot.add_cog(Greetings(bot)) # add the cog to the bot

You can add any number of commands to your cog, as well as event listeners. However, this code will not work on its own. In your main bot file, you must add the following code:

bot.load_extension('cogs.greetings')

This loads the file cogs/greetings.py and adds it to the bot. The argument of load_extension should be your cog's path (e.g. cogs/greetings.py) without the file extension and with the / replaced with .

If you have multiple cogs, you can add them all at once by adding the following code:

cogs_list = [
    'greetings',
    'moderation',
    'fun',
    'owner'
]

for cog in cogs_list:
    bot.load_extension(f'cogs.{cog}')

Cog Rules​

When using a cog instead of the main file, there are some changes you have to make to your code. This is because cogs work slightly different from a regular file.

The self variable​

The self variable is a variable that represents a class. In the case of cogs, self represents the cog. In the __init__ function, you can see that we have self.bot = bot. bot represents your discord.Bot or discord.ext.commands.Bot instance, which is used for some functions.

This means that instead of using functions that would usually be accessed via bot, you now need to access them via self.bot

Because we're in a class, all of our commands are methods of that class. Because of this, all of our functions need to have self as the first parameter, where self is the cog. Without this, we wouldn't be able to access our bot instance.

Creating Commands​

When creating prefixed commands, your decorator would usually be something like @bot.command(). If you're using cogs, this isn't the case. In a cog, you can't access the bot instance outside of functions, so to register a function as a command, you must instead use @commands.command().

Similar to prefixed commands, you'll have to use either the @discord.slash_command(), @discord.user_command(), or @discord.message_command() decorators for Application Commands.

Also, when creating a command, make sure that it is indented. If we want a command to be actually inside a cog, it has to be inside your cog's class. If the command is not inside the cog, your command becomes useless.

Events​

When creating events, you can no longer use @bot.event as a decorator. This is because we cannot access the bot variable outside a function. To make an event, you have to use the ext.commands method, @commands.Cog.listener(). Events also need self as their first parameter.

And that's it! Cogs are a simple and easy way of organizing your code. Now you can check out how to create a help command here.

Related Topics