DOCSEARCHbyAlgolia
Submit Docs

Red-DiscordBot Documentation

repository·V3/develop·Indexed 26 days ago

https://github.com/cog-creators/red-discordbot

A highly modular, self-hosted Discord bot framework that allows users to customize functionality through a plugin system called 'cogs'. It supports features including moderation, music, trivia, stream alerts, and automation. The documentation covers installation on Windows, MacOS, and Linux, the use of virtual environments for dependency isolation, auto-restart configurations via launchd, systemd, and batch files, and procedures for backing up and restoring bot instances.

Tokens
66.2K
Snippets
259
Records
527
Agent score
90%

What's inside Red-DiscordBot

  1. Overview of V3 Framework Changes

    V3/develop

    When migrating from V2 to V3, note the following architectural changes:

    • Cogs as Packages: Cogs are now treated as full Python packages. Refer to /guide_cog_creation for implementation details.
    • Config API: Replaces dataIO. It handles directory and file creation automatically and supports scoped storage (global, server, member, user, role, or channel).
    • Bank: Formerly part of Economy, Bank is now a standalone feature. It supports global banks and customizable bank/currency names.
    • Mod Log: Now provided as an API, allowing cogs to register custom case types for server moderation logs.

  3. Overview of Red Discord Bot

    V3/develop

    Red is a fully modular, self-hosted Discord bot designed for high customizability. It allows users to enable or disable specific features and commands to suit their needs. Because it is self-hosted, you are responsible for hosting and maintaining your own instance.

    Key features include:

    • Moderation: Kick, ban, softban, hackban, mod-logs, filters, and chat cleanup.
    • Music: Support for YouTube, SoundCloud, local files, playlists, and queues.
    • Trivia: Built-in lists and easy addition of new trivia.
    • Stream Alerts: Integration with Twitch, YouTube, and Picarto.
    • Automation: Self-role assignment, cross-server announcements, and mod-mail reports.
    • Other: Bank systems (slots, credits), custom commands, and Imgur/gif search.

  5. Use the red.core.app_commands package for Discord App Commands

    V3/develop
    The red.core.app_commands package provides a functional interface for creating Discord App Commands (Slash Commands). It is designed to be almost identical to discord.ext.app_commands from discord.py, meaning most attributes and behaviors are compatible. However, Red provides slight modifications to certain attributes and adds new functionalities to extend the bot's capabilities.

  7. Understand how the Permissions Cog works

    V3/develop

    The Permissions Cog allows you to define custom rules to restrict or grant access to specific commands, subcommands, or entire cogs.

    • Default Behavior: If no applicable rules are found, the command behaves according to its standard Discord/Red permissions.
    • Scope: Rules can be applied to a specific Command, a Subcommand, or an entire Cog (the cog name can be found in the help menu).
    • Rule Priority:
      1. Subcommand rules take precedence over Parent Command rules.
      2. Parent Command rules take precedence over Cog rules.
    • Global vs Server Scope:
      • Global rules are checked first.
      • Server rules are checked second.
    • Model Priority: Within a scope, the first rule found for the following models is used (in order):
      1. User
      2. Voice/stage channel the user is connected to
      3. The channel the command was issued in (or the parent channel if in a thread)
      4. Channel category
      5. Roles (highest to lowest)
      6. Server (Global rules only)
      7. Default rules
    • Private Messages: Only global rules pertaining to a user are checked.

  9. Create Context Menu Commands

    V3/develop

    Context menu commands appear under the Apps menu when a user right-clicks a message or a user in the Discord client. These commands accept exactly one argument: the contextual user or message that was right-clicked.

    To define them, use the @app_commands.context_menu(name="...") decorator. It is recommended to define these functions outside of your Cog class to ensure proper loading and unloading.

    import discord
from redbot.core import commands, app_commands

# Define commands outside the cog class
@app_commands.context_menu(name="Get message ID")
async def get_message_id(interaction: discord.Interaction, message: discord.Message):
    await interaction.response.send_message(f"Message ID: {message.id}", ephemeral=True)

@app_commands.context_menu(name="Get user ID")
async def get_user_id(interaction: discord.Interaction, user: discord.User):
    await interaction.response.send_message(f"User ID: {user.id}", ephemeral=True)

  11. Migrate MongoDB data to JSON (Red 3.1.X or 3.0.2 and older)

    V3/develop

    Red 3.2 dropped support for the MongoDB driver. If you are upgrading from an older version and were using MongoDB, you must convert your data to the JSON backend.

    For Red 3.1.X

    After updating to Red 3.5.25 but before launching your instance, run:

    python -m pip install dnspython~=1.16.0 motor~=2.0.0 pymongo~=3.8.0
redbot-setup convert [instancename] json

    For Red 3.0.2 and older

    Prior to updating, you must convert your data to the JSON backend using:

    redbot-setup --edit

    Note: If you were using 3rd-party cogs that required MongoDB, they may still require it even after this migration.

    # For 3.1.X (Post-update, Pre-launch)
python -m pip install dnspython~=1.16.0 motor~=2.0.0 pymongo~=3.8.0
redbot-setup convert [instancename] json

# For 3.0.2 and older (Pre-update)
redbot-setup --edit

  12. Extend Red with Plugins (Cogs)

    V3/develop

    Red's modularity is powered by plugins, referred to as cogs. You can load/unload built-in cogs or install 3rd party cogs directly from within Discord.

    • Browse Cogs: You can find a list of available 3rd party cogs at https://index.discord.red.
    • Examples of 3rd party cogs: Cleverbot integration, Ban sync, Welcome messages, Casino, Reaction roles, Slow Mode, and AniList.
    • Custom Development: If you cannot find a specific feature, you can build your own cog by following the cog creation guide.