Creating Custom Cogs
Relevant source files
The following files were used as context for generating this wiki page:
Red-DiscordBot uses a modular architecture where features reside in plugins called "cogs". Custom cogs allow you to extend the bot's functionality by adding new commands, event listeners, and data structures. This system enables users to enable or disable specific modules to customize the bot for their specific server needs.
Sources: README.md, CONTRIBUTING.md:120-122
Cog Structure and Metadata
Every cog exists as a Python package. For a cog to be recognized by Red's Downloader or the core management system, it should include metadata that defines its requirements, authors, and behavior.
Metadata Schema
Red utilizes a JSON schema to validate cog metadata. This information displays when users execute info commands or list available plugins.
| Property | Type | Description |
|---|---|---|
author | Array | List of names of authors of the cog. |
description | String | Detailed description displayed during [p]cog info. |
short | String | Brief description displayed during [p]cog list. |
min_bot_version | String | Minimum Red version required (MAJOR.MINOR.MICRO). |
requirements | Array | List of required libraries passed to pip on install. |
end_user_data_statement | String | Statement explaining what user data the cog stores. |
Sources: schema/red_cog.schema.json:7-73
Integration with Downloader
When you create a cog for distribution, the Downloader cog manages the installation of dependencies listed in your metadata. It also tracks which cogs are "pinned" to prevent automatic updates to specific versions.
Sources: redbot/cogs/downloader/downloader.py:349-410, redbot/cogs/downloader/downloader.py:821-835
Implementing the Cog Class
Custom cogs must inherit from commands.Cog. This base class allows the bot to register commands and listeners defined within your class.
Class Definition and Initialization
from redbot.core import commands
class MyCustomCog(commands.Cog):
"""Brief description of the cog."""
def __init__(self, bot):
self.bot = bot
Event Handling
Cogs can react to Discord events using the @commands.Cog.listener() decorator. The bot dispatches events like on_message, on_guild_join, and on_command_error to all loaded cogs.
Sources: redbot/cogs/permissions/permissions.py:530-550, redbot/core/_events.py:73-85
Command Implementation
Commands are the primary way users interact with cogs. You define them using the @commands.command() or @commands.group() decorators.
Command Help and Documentation
Red's help system extracts documentation from your command's docstrings. You can customize how help is displayed, including handling aliases and subcommands.
The RedHelpFormatter filters commands based on whether the user has permission to run them or if they are hidden.
Sources: redbot/core/commands/help.py:186-240, redbot/core/commands/help.py:537-567
Data Management and Privacy
Cogs that store data must implement specific methods to comply with data privacy requirements and Red's internal configuration system.
Configuration System
Cogs should use Red's Config library to store persistent data. This ensures data is stored correctly according to the bot's storage backend (e.g., JSON or MongoDB).
Sources: redbot/core/core_commands.py:202-210
End User Data Deletion
To support the [p]mydata forgetme command, every cog should implement red_delete_data_for_user. This method is called when a user requests their data be removed from the bot.
async def red_delete_data_for_user(self, *, requester, user_id):
# Logic to remove user data from self.config
pass
Sources: redbot/cogs/permissions/permissions.py:108-115, redbot/core/core_commands.py:440-520
Permissions and Security
Red provides a robust permission system that cogs can leverage. You can restrict commands to specific roles, server owners, or bot owners.
Customizing Access
Cogs like Permissions allow for fine-grained control over who can execute specific commands within a cog.
| Check Type | Description |
|---|---|
is_owner() | Restricts command to bot owners. |
guildowner() | Restricts command to the server owner. |
admin_or_permissions() | Checks for admin roles or specific Discord permissions. |
Sources: redbot/cogs/permissions/permissions.py:157-190, redbot/core/core_commands.py:1440-1450
Development Workflow
When developing custom cogs, Red's repository suggests specific tools to maintain code quality.
- Environment: Use
make newenvto set up a virtual development environment. - Style: Use
blackfor code formatting. Red sets the line length to 99 characters. - Testing: Use
toxto run unit tests and style checks. - Compatibility: Ensure your code works on Python 3.8.1 and above across Windows, macOS, and Linux.
Sources: CONTRIBUTING.md:52-110
Summary
Creating custom cogs involves defining a package with appropriate metadata, implementing a class that inherits from commands.Cog, and adhering to Red's standards for data privacy and command registration. By following the structured development workflow and utilizing the built-in configuration and permission systems, developers can create powerful, secure, and maintainable extensions for Red-DiscordBot.