Cog Management System
Relevant source files
The following files were used as context for generating this wiki page:
The Cog Management System governs the lifecycle, configuration, and execution of modular components called "Cogs" within Red. It provides mechanisms to load, unload, and reload code dynamically while maintaining stability through version compatibility checks and permission overrides. This system allows the bot to scale from a basic framework to a feature-rich application by integrating both core modules and community-developed extensions.
Sources: redbot/core/commands/commands.py, redbot/core/core_commands.py, redbot/cogs/downloader/downloader.py
Cog Architecture and Lifecycle
A Cog is a Python class that groups related commands, listeners, and state. Every Cog in Red must inherit from commands.Cog to integrate with the bot’s internal registries.
Lifecycle Events
The system triggers specific events when Cogs enter or exit the bot's runtime environment. The on_cog_add event occurs when a Cog is successfully loaded, allowing the system to apply global or guild-specific configurations, such as custom groups or command disablements.
The diagram shows the sequence of actions from a load request to a Cog becoming fully operational.
Sources: redbot/core/commands/commands.py:1126-1135, redbot/core/_events.py:382-389, redbot/core/core_commands.py:157-175
Core Logic Functions
The CoreLogic class handles the fundamental operations of the lifecycle. Key functions include:
_load: Imports packages, validates identifiers, and registers them in the bot's loaded package list._unload: Removes the extension from memory and cleans up associated package records._reload: Sequentially unloads and loads a package to apply code changes.
Sources: redbot/core/core_commands.py:112-250
Metadata and Schema Validation
Every Cog requires a metadata file to define its properties and requirements. Red uses a JSON schema to validate these files, ensuring consistency across the ecosystem.
Cog Metadata Properties
The following table summarizes key fields defined in the Cog schema.
| Property | Type | Description |
|---|---|---|
author | Array | Names of the Cog creators. |
min_bot_version | String | Minimum Red version required (MAJOR.MINOR.MICRO). |
requirements | Array | List of pip libraries needed for the Cog to function. |
end_user_data_statement | String | Description of user data stored by the Cog. |
hidden | Boolean | If true, hides the Cog from standard lists. |
Sources: schema/red_cog.schema.json:1-125
Compatibility Checking
The CogCompatibilityChecker ensures that installed Cogs remain functional after bot or environment updates. It categorizes Cogs based on their support for specific Red and Python versions.
Support Statuses
The system assigns a status to each Cog during checks:
- EXPLICITLY_SUPPORTED: The Cog metadata explicitly marks the current version as compatible.
- POTENTIALLY_SUPPORTED: No explicit incompatibility exists, but support is not confirmed.
- UNSUPPORTED_BOT_VERSION: The Cog requires a different Red version.
- UNSUPPORTED_PYTHON_VERSION: The system Python version is too old for the Cog.
This diagram illustrates how the compatibility checker interacts with the Downloader to evaluate Cog health during updates.
Sources: redbot/_update/cog_compatibility_checker.py:180-230
Command and Cog Management Commands
The Core Cog provides user-facing commands to manage the system via Discord. Owners use these commands to manipulate the bot's feature set at runtime.
Management Command Summary
| Command | Restriction | Purpose |
|---|---|---|
[p]load | Owner | Loads one or more Cog packages. |
[p]unload | Owner | Unloads specified Cogs. |
[p]reload | Owner | Restarts Cogs to apply updates. |
[p]command disablecog | Admin | Disables a Cog within a specific server. |
[p]command defaultdisablecog | Owner | Disables a Cog for all servers by default. |
Sources: redbot/core/core_commands.py:1022-1175, redbot/core/core_commands.py:2020-2100
Interaction with Downloader
The Downloader Cog extends management capabilities by allowing users to install 3rd-party Cogs from remote Git repositories. It handles the cloning of repositories and the installation of Python dependencies via pip.
Sources: redbot/cogs/downloader/downloader.py:44-60
Permissions and Access Control
Cogs and their commands use a hierarchical permission system. If global or server-specific rules are defined, the system checks them before executing any command callback.
Evaluation Order
- Global Rules: Set by the bot owner.
- Server Rules: Set by guild administrators.
- Internal Requirements: Checks defined in the code (e.g.,
requires.bot_perms).
If a Cog is disabled in a guild via disable_in, its commands will not execute for users in that guild, regardless of other permission settings.
Sources: redbot/core/commands/commands.py:910-955, redbot/core/core_commands.py:2054-2065
Conclusion
The Cog Management System provides a robust foundation for Red's modularity. By combining dynamic loading, strict metadata validation, and comprehensive compatibility checking, Red ensures that developers can extend bot functionality while administrators maintain control over the security and stability of their instances.