🧹 Janitor Bot

A modern Discord bot built with slash commands, featuring interactive games, moderation tools, and customization features.

---

📋 Table of Contents

• Features
• Commands
  • Information
  • Fun & Games
  • Moderation
  • Administration
  • Customization
• Configuration
• Project Structure
• Database
• License

---

✨ Features

🎮 Interactive Entertainment

• Russian Roulette Duel - Button-based duel system with win/loss tracking and leaderboards
• Fork Duel - Number guessing game with dynamic timeout mechanics
• Urban Dictionary - Paginated definition browser with stats and examples
• Quote System - Smart message scraper with anti-repeat logic
• Birthday Tracking - Automated role assignment with database sync

🛡️ Moderation Suite

• Advanced Purge - Bulk message deletion with full logging to text files
• Timeout System - Flexible duration-based user timeouts
• Media Restrictions - Granular control over attachment permissions
• Channel Management - Lock/unlock channels and configure slowmode

🎨 Customization

• Personal Roles - Users can create and customize up to 2 personal roles
• Flexible Colors - Supports hex codes, color names, and shorthand notation
• Auto-Positioning - Roles automatically positioned above user's highest role

⚙️ Technical Features

• Slash Commands - Native Discord command integration
• Modular Architecture - Organized cog system for maintainability
• SQLite Database - Persistent storage for stats, birthdays, and custom roles
• JSON Configuration - Easy-to-edit centralized settings
• Comprehensive Logging - File and console logging for debugging
• Status Updates - Auto-updating Colorado time display

---

📚 Commands

🔍 Information Commands

Command	Description	Example
/help	Display bot information	/help
/commands [category]	List commands by category	/commands fun
/whois [user]	Detailed user profile with badges	/whois @User
/ping	Check bot latency	/ping
/uptime	Show bot uptime	/uptime
/birthdays [channel]	View upcoming birthdays	/birthdays #general
/setbirthday <day> <month>	Set your birthday	/setbirthday 15 March
/mybirthday [user]	Check birthday	/mybirthday @User
/removebirthday	Remove your birthday	/removebirthday

Whois Features:

• Works for users outside the server (via ID)
• Displays Discord badges (HypeSquad, Bug Hunter, Early Supporter, etc.)
• Shows user banners, avatars, and server-specific information
• Includes account age, join date, roles, and timeout status

Birthday System:

• Accepts multiple formats: 15 March, 3/15, Mar 15
• One birthday per user limit
• Auto-assigns configured birthday role
• Database-backed with role sync via /bdsync

---

🎮 Fun & Games

Command	Description	Example
/quote [user]	Random quote from user's history	/quote @User
/coinflip	Flip a coin	/coinflip
/8ball <question>	Magic 8-ball predictions	/8ball Will it rain?
/urban <word>	Urban Dictionary with pagination	/urban yeet
/define <word>	Dictionary definition	/define serendipity
/broomfight <user>	Random outcome duel	/broomfight @User
/fork [target]	Number guessing duel	/fork @User
/rrd <target>	Russian Roulette duel	/rrd @User
/duelstats [user]	View duel statistics	/duelstats @User
/rrdleaderboard	Top 5 duelers	/rrdleaderboard

Quote System:

• Scans up to 2,000 messages across accessible channels
• Filters out URLs, attachments, and embeds
• Minimum 20 characters per quote
• Prevents repeating last 4 quotes

Fork Duel:

• Guess number between 1-100
• Win if within ±9 of target number
• Winner: Target gets 5-minute timeout
• Loser: You get 85-second timeout
• 10-minute cooldown between uses

Russian Roulette:

• Button-based challenge/accept system
• Truly random turn order
• Single-message updates (no spam)
• 60-second timeout for loser
• 30-second cooldown
• Full statistics tracking

Urban Dictionary:

• Browse all definitions with Previous/Next buttons
• Shows author, upvotes, downvotes
• Page counter and examples
• 3-minute auto-timeout

---

🔨 Moderation (Admin Only)

Command	Description	Example
/ban <user> [duration] [reason] [delete_days]	Ban user	/ban @User 7d Spam
/timeout <user> [duration] [reason]	Timeout user	/timeout @User 30min
/removetimeout <user>	Remove timeout	/removetimeout @User
/lock [channel]	Lock channel	/lock #general
/unlock [channel]	Unlock channel	/unlock #general
/slowmode <seconds> [channel]	Set slowmode	/slowmode 10
/purge <amount> [user]	Bulk delete messages	/purge 50
/mediarestrict <user> [duration]	Restrict media	/mediarestrict @User 1h
/mediaunrestrict <user>	Remove restriction	/mediaunrestrict @User

Duration Formats:

• 30min - 30 minutes
• 2h - 2 hours
• 1d - 1 day
• 1w - 1 week
• 1m - 1 month
• 1y - 1 year

Purge Features:

• Bulk delete up to 350 messages
• Optional user filter
• Full logging to configured channel
• Exports deleted messages to text file
• Includes timestamps and authors

---

⚙️ Administration (Admin Only)

Command	Description	Example
/setlog <channel>	Set log channel	/setlog #mod-log
/clearlog	Clear log channel	/clearlog
/clonerole <role> <name>	Clone role	/clonerole @Mod ModBackup
/removerole <role>	Delete role	/removerole @OldRole
/speech <channel> <message>	Send as bot	/speech #general Hello!
/setpic <image>	Update avatar	/setpic (attach image)
/setbanner <image>	Update banner	/setbanner (attach image)
/setusername <name>	Change username	/setusername JanitorBot
/setstatus <status>	Set status	/setstatus Cleaning
/bdsync	Sync birthday roles to DB	/bdsync

Birthday Sync:

• Scans all server roles for birthday format ("5th April")
• Auto-saves members to database
• Shows detailed sync report (new/updated/skipped)
• One birthday per user enforcement

---

🎨 Customization

Command	Description	Example
/customize [role] [name] [color] [nickname]	Customize personal role	/customize color:#FF5733
/mycustomroles	View your custom roles	/mycustomroles

Customize Features:

• Create up to 2 custom roles per user
• Auto-positioned above user's highest role
• Flexible color input:
  • Hex: #FF5733 or FF5733
  • Shorthand: #F00 → #FF0000
  • Names: red, blue, purple, gold
• Edit name, color, and nickname simultaneously
• Protected roles list (configured in code)
• Database tracking to prevent abuse

Examples:

/customize name:VIP color:gold
/customize color:#00FF00 nickname:Bob
/customize role:@MyRole name:Elite

---

⚙️ Configuration

config.json Structure

{
  "token": "YOUR_BOT_TOKEN",
  "genius_token": "GENIUS_API_TOKEN",
  
  "bot_info": {
    "developer": "GXTHICKITTY",
    "host_provider": "Personal Device",
    "version": "2.0",
    "description": "Washing Machine"
  },
  
  "colors": {
    "primary": "a84141"
  },
  
  "roles": {
    "birthday_role_id": 1214960856085962762
  },
  
  "cooldowns": {
    "duel_seconds": 30,
    "fork_minutes": 10,
    "fork_timeout_minutes": 5
  },
  
  "limits": {
    "purge_max": 350,
    "quote_scan_limit": 2000,
    "quote_min_length": 20,
    "quote_history_size": 4
  },
  
  "database": {
    "path": "data/bot.db"
  },
  
  "logging": {
    "log_channel_id": null
  }
}

Protected Roles

Edit cogs/customize.py to add protected role IDs:

self.protected_roles = [
    123456789012345678,  # Admin role
    234567890123456789,  # Moderator role
]

---

📁 Project Structure

janitor-bot/
├── main.py                    # Bot entry point
├── config.json                # Configuration
├── requirements.txt           # Dependencies
│
├── utils/                     # Utility modules
│   ├── config.py             # Config manager
│   ├── database.py           # Database interface
│   ├── helpers.py            # Helper functions
│   └── logger.py             # Logging setup
│
├── cogs/                      # Command modules
│   ├── admin.py              # Admin commands + bdsync
│   ├── moderation.py         # Moderation tools
│   ├── fun.py                # Fun commands + urban
│   ├── games.py              # Duel systems
│   ├── info.py               # Info + birthdays
│   └── customize.py          # Role customization
│
├── data/                      # Auto-created
│   └── bot.db                # SQLite database
│
└── logs/                      # Auto-created
    └── bot.log               # Application logs

Cog Breakdown

admin.py

• Bot configuration (avatar, banner, username, status)
• Role management (clone, delete)
• Message sending
• Birthday role sync
• Log channel configuration

moderation.py

• User punishment (ban, timeout)
• Channel controls (lock, unlock, slowmode)
• Message purging with logs
• Media restrictions

fun.py

• Quote system
• Coin flip & 8-ball
• Urban Dictionary (paginated)
• Regular dictionary
• Broom fight
• Fork duel

games.py

• Russian Roulette duel
• Duel statistics
• Leaderboard

info.py

• Bot information
• Command list
• User lookup (whois)
• Birthday system (view, set, remove)
• Ping & uptime

customize.py

• Personal role creation
• Color & name customization
• Nickname setting
• Role tracking

---

🗄️ Database

Tables

duel_stats

• user_id (PRIMARY KEY)
• wins (INTEGER)
• losses (INTEGER)
• last_duel (INTEGER, timestamp)

custom_roles

• user_id (INTEGER)
• role_id (INTEGER)
• created_at (INTEGER, timestamp)
• PRIMARY KEY: (user_id, role_id)

birthdays

• user_id (PRIMARY KEY)
• day (INTEGER, 1-31)
• month (INTEGER, 1-12)

Key Features

• Auto-initialization on startup
• One birthday per user enforcement
• Duel win/loss tracking
• Custom role abuse prevention (2 max per user)
• Automatic cleanup of deleted roles

---

🎯 Special Features

Auto-Updating Status

• Displays current Colorado time (MST/MDT)
• Updates every 10 minutes
• Format: Time in Colorado, US - 14:35
• Automatic daylight saving time handling

Birthday Role Sync

• Parses roles like "15th January", "3rd March"
• Auto-saves users to database
• Admin command: /bdsync
• Prevents duplicate birthdays per user
• Multiple users can share same birthday

Quote Intelligence

• Scans 2000+ messages efficiently
• Filters URLs, embeds, attachments
• Minimum length requirement (20 chars)
• Anti-repeat system (last 4 quotes)
• Respects channel permissions

Duel Fairness

• True randomization (no bias)
• Turn order shuffled
• Bullet position shuffled
• Single-message updates
• Comprehensive statistics

---

📄 License

MIT License

Copyright (c) 2024 LAPPISU

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

Janitor Bot v2.0 • Built with ❤️ and Discord.py