Creating cogs for V3¶
This guide serves as a tutorial on creating cogs for Red V3. It will cover the basics of setting up a package for your cog and the basics of setting up the file structure. We will also point you towards some further resources that may assist you in the process.
To start off, be sure that you have installed Python 3.7.
Open a terminal or command prompt and type
pip install -U git+https://github.com/Cog-Creators/Red-DiscordBot@V3/develop#egg=redbot[test]
(note that if you get an error with this, try again but put
python -m in front of the command
This will install the latest version of V3.
Setting up a package¶
To set up a package, we would just need to create a new folder.
This should be named whatever you want the cog to be named (for
the purposes of this example, we’ll call this
In this folder, create three files:
info.json. Open the folder in
a text editor or IDE (examples include Sublime Text 3,
Visual Studio Code, Atom, and
While you can intentionally override Red’s cogs/extensions, this may break things. We would prefer if people wanted custom behavior for any core cog/extension, an issue and/or PR is made Overriding Permissions specifically is dangerous.
Subclassing to make changes to Red’s cogs/extensions may not be a safe way to stay up to date either, as changes to cogs and their interactions with red are not guaranteed to not be breaking.
Any cogs doing this are doing so at their own risk, and should also inform users of associated risks.
Creating a cog¶
With your package opened in a text editor or IDE, open
In that file, place the following code:
from redbot.core import commands class Mycog(commands.Cog): """My custom cog""" @commands.command() async def mycom(self, ctx): """This does stuff!""" # Your code will go here await ctx.send("I can do stuff!")
__init__.py. In that file, place the following:
from .mycog import Mycog def setup(bot): bot.add_cog(Mycog())
Make sure that both files are saved.
Testing your cog¶
To test your cog, you will need a running instance of V3.
Assuming you installed V3 as outlined above, run
and provide the requested information. Once that’s done, run Red
redbot <instance name> --dev to start Red.
Complete the inital setup by providing a valid token and setting a
prefix. Once the bot has started up, use the link provided in the
console to add it to a server (note that you must have the
Manage Server (or
Administrator) permission to add bots
to a server). Once it’s been added to a server, find the full path
to the directory where your cog package is located. In Discord, do
[p]addpath <path_to_folder_containing_package>, then do
[p]load mycog. Once the cog is loaded, do
The bot should respond with
I can do stuff!. If it did, you
have successfully created a cog!