Custom Cogs

BotBox makes it easy to add your own custom features as cogs.
A cog is just a Python class in src/cogs/ that groups related commands and logic.

Creating a Custom Cog

You can use botbox add for interactive generation, or create a cog manually.

Manual Example

Create a new file in src/cogs/ (e.g., myfeature.py):

import discord
from discord.ext import commands

class MyFeature(commands.Cog):
    def __init__(self, bot):
        self.bot = bot

    @commands.command()
    async def ping(self, ctx):
        """Replies with pong."""
        await ctx.send("pong")

async def setup(bot):
    await bot.add_cog(MyFeature(bot))

Registering Your Cog

If you create a cog manually, add it to your botbox.conf under the cogs array:

{
  "name": "MyFeature",
  "file": "myfeature",
  "env": "development",
  "slash_commands": [],
  "prefix_commands": [
    {
      "Name": "ping",
      "Type": "prefix",
      "Scope": "guild",
      "Description": "Replies with pong.",
      "Args": [],
      "ReturnType": "None"
    }
  ]
}

Or, run:

botbox config sync

to automatically update your config based on the files in src/cogs/.

botbox config sync also recognizes hand-written modal commands. A command whose body calls send_modal(SomeModal()) is recorded with "Type": "modal", and the TextInput assignments on that class are read back as its fields. See Modal Commands.

Logging From a Cog

Generated projects ship src/utils/logger.py. Use get_logger so your cog's output goes to logs/bot.log and stdout with the same formatting as the rest of the bot.

from utils.logger import get_logger

logger = get_logger(__name__)

class MyFeature(commands.Cog):
    def __init__(self, bot):
        self.bot = bot
        logger.info("MyFeature loaded")

The level comes from LOG_LEVEL and the directory from LOG_DIR, see Environment Variables.

Best Practices

• Keep each feature in its own cog file
• Use descriptive class and file names
• Document your commands with docstrings
• Log through get_logger rather than print

Next Steps

• Environment Variables
• Troubleshooting