Skip to content

README.md

Latest commit

 

History

History
267 lines (207 loc) · 8.23 KB

README.md

File metadata and controls

267 lines (207 loc) · 8.23 KB

Discord Moderation Bot

A feature-rich Discord bot built with discord.py that provides moderation tools, interactive UI components, and automated content filtering.

Features

🛡️ Moderation & Auto-Moderation

  • Profanity Filter: Automatically detects and deletes messages containing banned words
  • Strike System: Tracks user violations with automatic banning after reaching threshold
  • Spam Detection: Identifies and bans users sending too many messages in a short time window
  • Manual Moderation: Commands for kick, ban, unban, and role management
  • Mod Logging: Optional logging channel for all moderation actions

🎨 Interactive Components

  • Color Role Selection: React-based role assignment system with emoji reactions
  • Dropdown Menus: Interactive select menus for user choices
  • Buttons: Custom button interfaces with multiple styles
  • Embeds: Rich embedded messages with formatting

💬 Basic Features

  • Slash commands for modern Discord interaction
  • Message event handlers
  • Reaction role system
  • Custom greetings

Prerequisites

Installation

  1. Clone the repository

    git clone https://github.com/EarnTHYPart/DiscordBot.git
cd DiscordBot

  2. Create a virtual environment

    python -m venv .venv

  3. Activate the virtual environment

    • Windows (PowerShell): 
      .\.venv\Scripts\Activate.ps1
    • Windows (Git Bash): 
      source .venv/Scripts/activate
    • Linux/Mac: 
      source .venv/bin/activate

  4. Install dependencies

    pip install -r requirements.txt

  5. Configure environment variables

    Copy the example file and fill in your values:

    cp .env.example .env

    Or create a .env file manually:

    DISCORD_BOT_TOKEN=your_bot_token_here
DISCORD_GUILD_ID=your_server_id_here
MOD_LOG_CHANNEL_ID=your_log_channel_id_here
BANNED_WORDS=word1,word2,word3
SPAM_TIME_WINDOW=7
SPAM_MESSAGE_LIMIT=5
STRIKES_TO_BAN=3
COMMAND_PREFIX=!

Configuration

The bot uses a centralized configuration system through config.py which loads all settings from your .env file.

Environment Variables

Variable Description Default
DISCORD_BOT_TOKEN Your bot's authentication token Required
DISCORD_GUILD_ID Your Discord server ID Required
MOD_LOG_CHANNEL_ID Channel ID for moderation logs Optional
BANNED_WORDS Comma-separated list of profanity ``
SPAM_TIME_WINDOW Time window for spam detection (seconds) 7
SPAM_MESSAGE_LIMIT Max messages allowed in time window 5
STRIKES_TO_BAN Number of strikes before auto-ban 3
COMMAND_PREFIX Bot command prefix !

Note: An .env.example file is provided as a template. Copy it to .env and fill in your actual values.

Bot Permissions

Ensure your bot has these permissions:

  • Send Messages
  • Manage Messages (for deleting profanity/spam)
  • Manage Roles (for color roles and role commands)
  • Ban Members (for auto-moderation)
  • Kick Members (for manual moderation)
  • Add Reactions (for reaction roles)
  • Read Message History
  • View Channels

Setting Up Roles

For the color role system to work, create these roles in your server:

  • Red
  • Green
  • Blue
  • Yellow
  • Pink

Usage

Running the Bot

Basic version (main.py - simplified features):

python main.py

Advanced version (secondary.py - full moderation):

python secondary.py

Available Commands

Slash Commands (/)

Command Description Permission Required
/hello Bot greets you Everyone
/print <text> Echo text back Everyone
/embed Display an example embed Everyone
/menu Show a dropdown menu Everyone
/button Display interactive buttons Everyone
/colorrole Create color role selection message Administrator

Prefix Commands (!)

Command Description Permission Required
!ping Check bot latency Everyone
!addrole @user <role> Add role to user Manage Roles
!removerole @user <role> Remove role from user Manage Roles
!kick @user [reason] Kick a user Kick Members
!ban @user [reason] Ban a user Ban Members
!unban username#0000 Unban a user Ban Members
!mention <text> Send a mention message Administrator

Auto-Moderation Features

Profanity Filter:

  • Automatically deletes messages containing banned words
  • Issues strikes to offending users
  • Auto-bans users after reaching strike threshold
  • Logs all actions to mod log channel

Spam Detection:

  • Monitors message frequency per user
  • Auto-bans users exceeding message limit in time window
  • Configurable thresholds via environment variables

Reaction Roles:

  • Use /colorrole to create a color selection message
  • Users react with emoji to get corresponding role
  • Removing reaction removes the role

Project Structure

DiscordBot/
├── main.py              # Basic bot implementation
├── secondary.py         # Advanced bot with full moderation
├── config.py            # Centralized configuration module
├── requirements.txt     # Python dependencies
├── strikes.json         # Persistent strike data (auto-generated)
├── .env                 # Environment configuration (create this)
├── .env.example         # Example environment configuration
├── .gitignore          # Git ignore file
└── README.md           # This file

Files Description

  • main.py: Simplified version with basic commands, reaction roles, and UI components
  • secondary.py: Full-featured version with auto-moderation, profanity filter, spam detection, and all commands
  • config.py: Centralized configuration management - loads and validates all settings from .env
  • strikes.json: JSON file storing user strike counts (automatically created)
  • .env.example: Template for environment variables - copy to .env and configure
  • requirements.txt: List of required Python packages

Dependencies

  • discord.py - Discord API wrapper
  • python-dotenv - Environment variable management
  • requests - HTTP library
  • aiohttp - Async HTTP client/server

See requirements.txt for complete list with versions.

Troubleshooting

Bot not responding to commands

  • Verify bot token is correct in .env
  • Check bot has proper permissions in your server
  • Ensure GUILD_ID matches your Discord server ID
  • Commands may take a minute to sync after first startup

Color roles not working

  • Create roles named exactly: Red, Green, Blue, Yellow, Pink
  • Ensure bot's role is higher than color roles in hierarchy
  • Bot needs "Manage Roles" permission

Profanity filter not working

  • Check BANNED_WORDS in .env is set correctly
  • Bot needs "Manage Messages" permission
  • Ensure secondary.py is being used (not main.py)

Module not found errors

  • Activate virtual environment
  • Run pip install -r requirements.txt

Contributing

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/NewFeature)
  3. Commit your changes (git commit -m 'Add NewFeature')
  4. Push to the branch (git push origin feature/NewFeature)
  5. Open a Pull Request

Security Notes

  • Never commit your .env file - it contains sensitive tokens
  • Add .env to .gitignore
  • Rotate your bot token if accidentally exposed
  • Use environment variables for all sensitive configuration

License

This project is provided as-is for educational and personal use.

Support

For issues and questions:

Note: This bot includes two versions:

  • main.py: Lightweight version for basic functionality
  • secondary.py: Production-ready version with comprehensive moderation

Choose the version that best fits your needs!