Version: 2.0.1
Here are the maximum uses and testbeds for Bird Bot. Note that this is a server mainly for Chinese speakers in Europe, anyone is welcome to join, but please respect the culture of the server and follow the server rules.
The purpose of developing this bot is to avoid the use of various current e.g. MEE6, ProBot and other existing server managed robots. This allows for maximum personalisation and control of features and interfaces and avoids the introduction of too many public bots.
The bot incorporates the functionality used in several bots and has been developed with additional fun features. Therefore, the bot is currently only intended for use with a single server and there are no plans to support multiple servers at this time. Anyone can download the bot and run it on their own server. All data processing and storage is done locally.
The bot's code is deeply optimised for low-performance devices, using asynchronous handling of API responses and database operations. Therefore, for this bot working on a 10k members and 500 online voice users server, a 1 vCPU + 1GB RAM cloud server for about $5 a month is perfectly adequate for performance.
discord.py, aiosqlite, sqlcipher3, aiohttp, requests, aiofiles, pillow, matplotlib, tqdm, PySimpleGUI, ruamel.yaml
- Clone the repository and enter the directory.
- Recommended: sync the virtual environment with the locked Python version in
.python-version.uv sync --python 3.12.3source .venv/bin/activate- Optional test tooling:
uv sync --extra test - Optional lint tooling:
uv sync --extra lint
- Dependency management is centralized in
pyproject.tomlanduv.lock.pyproject.tomlis the human-maintained direct dependency list.uv.lockis the canonical reproducible lock file.requirements.lockis a compatibility export generated fromuv.lock; do not edit it by hand.
- Copy only the required
*.yaml.examplefiles inbot/config/, rename them to*.yaml, and fill in the values. Run-time configs are YAML (since config 2.0); legacyconfig_*.json.exampletemplates were moved to thelegacy-old-files-archivebranch for historical reference. - In
main.yaml, usefeaturesto enable only the modules you need.- Relative runtime paths such as
./data/bot.dband./data/bot.logare resolved from the repository root. - For encrypted database storage, set
DCGSH_DB_KEY_FILEto a secret file outside the repository in production. For first-run key-file generation, also setDCGSH_DB_CREATE_KEY_FILE=1, run the migration withpython -m tools.encrypt_database, then remove the create flag and setDCGSH_DB_REQUIRE_ENCRYPTION=1in production. run.pyloads a repository-local ignored.envfile before importing the bot. This is intended for local test environments; if.envuses a relativeDCGSH_DB_KEY_FILE, the path is resolved from the.envfile's directory. Environment variables supplied by the launcher take precedence.
- Relative runtime paths such as
- Disabled modules, or modules without a valid config file, will be skipped during startup and their commands will not be registered.
- If migrating from a pre-config-2.0 deployment: run
python tools/migrate_config_to_yaml.pyto produce YAML + locale files from your existingconfig_*.json, reviewtools/migration_report.md, then runpython tools/seed_db.pyto loadvoicechannel.channel_configs/tickets.ticket_typesinto the database (these were JSON-subtree-turned-DB-tables in P2-5; note: legacyconfig_tickets_new.jsonsources are auto-mapped to the newticketsname, while removed-system sourcesconfig_tickets.jsonandconfig_rating.jsonare skipped). SeeREFACTORING_PROGRESS.md"Upgrade 协议" for the full sequence. - In the Discord Developer Portal, enable the privileged intents required by this bot:
Server Members IntentandMessage Content Intent. The runtime does not requestPresence Intent. - Run
python run.py. If you are using a Linux server, you can usenohup python3 run.py &to run the bot in the background. - Invite the bot to your server and give it the necessary permissions.(Required permissions: bot, application command, administrator)
InviteGuard_Cogneeds permission to list active guild invites and delete invites. In Discord terms this is usuallyManage Server/Manage Guild; depending on where the invite was created, relevant channelManage Channelspermission may also be needed.- Invite leaderboard attribution also needs
Server Members Intentfor join/leave events and permission to list guild invites. To update the leaderboard message, the bot needs View Channel, Send Messages, Read Message History, and permission to edit its own message in the target channel.
- Run automated smoke tests with
python -m pytestwhen the test extra is installed. The suite covers config templates, runtime cog metadata, log helpers, UI locale metadata, the temporary JSON-to-YAML config migration smoke, background-loop offline guards, and pure DB-manager paths with temporary sqlite databases. - Run the bare-except lint guard with
python -m ruff check bot testswhen the lint extra is installed. - For updating the bot, you can use the
git pullcommand to update the bot to the latest version, then rerunuv sync. - For the Tickets cog, use
/tickets_initto initialize the ticket system. Please check function introduction for more details.
When a user enters a specific channel, the bot creates a new channel of the corresponding type and moves the user to the new channel. Similarly, if the channel was created by the bot, the bot will delete the channel when the last user leaves the channel.
Enhanced Features:
- Interactive control panel with 4-button interface in voice channel text chat
- Room management buttons: Unlock (public), Lock (private), Full (mark teamup as full), Soundboard (toggle)
- Dynamic panel appearance with color-coded embeds based on room type
- Auto-recovery system restoring control panels after bot restart
- Startup-safe temp channel cleanup that creates/migrates
temp_channelsbefore background cleanup starts
Commands:
/check_temp_channel_records: Query the temporary voice channel records of the current server. This command is mainly used to check that the robot's mechanism of automatically deleting rooms that no longer exist every hour is working properly./vc_add <channel>: Add a voice channel that automatically creates new voice channels./vc_remove [channel] [channel_id]: Remove a voice channel that automatically creates new voice channels. Use channel selection or channel ID (for deleted channels)./vc_list: List all voice channels that automatically create new voice channels.
A user sends a teaming message and bot replies with an invitation link to that user's channel to make it easy for other users to quickly join the user's room.
If the user is not currently on a channel, bot will prompt the user to create a new channel using Voice_Channel_Cog first.
Enhanced Features:
- Intelligent keyword detection using regex patterns to automatically detect team-up requests
- User signature system allowing personalized signatures in invitations
- Room status tracking with "room full" functionality
- Separate logging system for keyword detection activities
Commands:
/invt <title>: Create an invitation with a specified title(optional)./invt_checkignorelist: Check the current server's invitation channel ignore list./invt_addignorelist <channel>: Add a channel to the invitation channel ignore list./invt_removeignorelist [channel] [channel_id]: Remove a channel from the invitation channel ignore list. Use channel selection or channel ID (for deleted channels).
Silent invite cleanup for servers where long-lived 30-day invites accumulate and block new invite creation, plus an invite leaderboard that attributes new members by comparing Discord invite uses deltas.
Features:
- Daily scan of the configured guild's active invites
- Silent deletion of invites older than the configured age, default 3 days
- Invite-code whitelist for official permanent invites
- Creator whitelist for selected users; bot owner, Discord administrators, and members who can access the configured admin channel are treated as admin-side creators
- Dry-run mode for testing without deleting invites
- Console / bot log summary after every scheduled cleanup run
- Invite leaderboard DB tables:
invite_usersstores invite counts and attribution locks;invite_linksstores invite code metadata, uses, active state, and ignored status - Startup invite cache plus 5-minute invite-link sync and leaderboard message edit
- Components v2 invite leaderboard panel with Top 15 entries, viewer-local relative update time, separators, and bot avatar thumbnail
- Member join attribution based on invite
usesdeltas, settled in a short batch window (default 2 seconds); ignored, unknown, or ambiguous joins remain re-attributable, while a successful attribution locks the joined member permanently - Pooled attribution for same-window joins: when the total invite-use delta matches the batch size, each inviter is credited (full attribution if a single invite absorbed the whole batch,
pooled_countotherwise) and rewarded; inconsistent batches degrade to ambiguous with zero reward - Member leave tracking without reducing counts, so rejoin loops do not add more points
- Configurable Shop point reward for each newly counted valid invite; default is 60 points
- Reward notification DM to the inviter after points are credited: a Components v2 message with the reward summary, the
resources/images/invite_reward.pngimage, and a leaderboard link button jumping to the panel message; only sent while a valid leaderboard panel exists
Commands:
/invite_sync: Sync current Discord invite links and refresh the leaderboard panel./invite_check_user <member>: Show one member's invite count, attribution status, join count, and leave count./invite_create_embed <channel>: Create a new leaderboard panel in the target channel; the name keeps "embed" for operator familiarity, but the panel uses Discord Components v2.
Config:
- Copy
bot/config/invite_guard.yaml.exampletobot/config/invite_guard.yaml - Set
features.invite_guard: trueinmain.yaml - Add official invite codes to
invite_code_whitelist - Optional: set
dry_run: truefirst and inspect logs before allowing deletion - Invite cleanup and leaderboard both use
main.guild_id; InviteGuard does not have a separate guild setting. - Set
leaderboard_channel_id; optionally setleaderboard_message_idif a message already exists. If no message ID is configured, the bot creates one and logs the ID to save. - Put official / vanity entry codes such as
birdgaminginignored_codesorinvite_code_whitelistso they never count toward the leaderboard. - Set
reward_points_per_inviteto control the points awarded for each newly counted valid invite; default is60, and0disables invite rewards. pooled_attribution_enabled(defaulttrue) enables pooled crediting for same-window multi-invite joins;attribution_batch_window_seconds(default2) controls the join settlement window.reward_notification_enabled(defaulttrue) sends the reward DM to the inviter when points are credited and a valid leaderboard panel exists;reward_notification_imagenames the image file underresources/images/.
Attribution limits:
- Discord does not expose the invite code directly in
on_member_join; the bot infers it by comparing cached invite uses against a freshguild.invites()snapshot. - Attribution can be unknown or ambiguous when the bot was offline, lacks invite-list permissions, the user joined through vanity / Discovery / official entry, or same-window invite-use deltas do not add up to the number of joined members; pooled attribution covers the matching multi-join cases.
When a new user joins the server, the bot sends a welcome message to the user in the welcome channel with enhanced features:
Features:
- Dynamic welcome images with user avatars and member count
- Customizable welcome messages with font and styling support
- Automatic DM system sending personalized direct messages to new members
- Resource verification system to ensure required assets are available
- Server statistics integration displaying current member count
Commands:
/testwelcome <member> <member_number>- Send the welcome message for specific member with specific number.- For default
<member>is the user who uses the command,<member_number>is the total number of people in the server.
- For default
Provide enhanced monitoring and status checking functions with comprehensive data tracking.
Enhanced Logging System:
- Triple log system supporting main application, keyword detection, and room activity logs
- Log file size management with automatic file generation for large logs
- Chinese interface for better user experience
Voice Monitoring:
- Real-time voice statistics with database storage
- Automated data collection every 10 minutes for trend analysis
- Chart generation capabilities for activity visualization
- Category-based tracking of voice channel usage
Commands:
/check_log <number=x> [log_type=main]- Returns the lastxlines of the specified log file. Choose from main, keyword, or room activity logs./check_voice_status- Returns comprehensive voice channel statistics and member counts./where_is <member>- Returns the position of the selected member within the channel. Only visible to user./print_voice_status- Print the longtime server voice channel and number information./test_keyword_log [test_message]- Test the keyword detection logging system.
Comprehensive achievement tracking system for user activity monitoring.
Features:
- Message Count Tracking: Monitor user message activity with milestone achievements
- Reaction Count Tracking: Track reaction usage with progress rewards
- Voice Time Tracking: Monitor time spent in voice channels with time-based achievements
- Monthly Statistics: View achievements and rankings by specific months
- Admin Management: Manual adjustment capabilities for achievement progress
- Feature-linked visibility: achievement categories tied to disabled modules are automatically hidden from progress pages, rankings, and manual adjustment flows
Commands:
/achievements [member] [date]: View user achievements. Use<date>format like "2024-07" for monthly views./increase_achievement <member> [reactions] [messages] [time_spent]: Manually increase achievement progress./decrease_achievement <member> [reactions] [messages] [time_spent]: Manually decrease achievement progress./achievement_ranking [date]: Show top 10 users in various achievement categories./check_ach_ops: Check manual operation history for the achievement system./rank: Enhanced ranking system interface for server leaderboards.
Comprehensive role assignment system with multiple assignment categories.
Features:
- Achievement-based role assignment with automatic role updates
- Star sign role system with 12 zodiac options
- MBTI personality role system with all 16 types
- Gender role assignment with inclusive options
- User signature system with permission management and voice time requirements
- Role panel preflight validation blocking panel creation when referenced role IDs are missing or invalid
- Optional starter roles allowing
achievement_start_role_idandsocial_start_role_idto be left empty without runtime errors
Commands:
/create_role_pickup <channel>: Create achievement role selection interface/create_starsign_pickup <channel>: Create star sign role selection interface/create_mbti_pickup <channel>: Create MBTI role selection interface/create_gender_pickup <channel>: Create gender role selection interface/create_signature_pickup <channel>: Create signature management interface/signature_permission_toggle <user_id> <disable>: Toggle user's signature permissions/signature_clear <user_id>: Clear user's signature and history/signature_set_requirement <minutes>: Set voice time requirement for signatures/signature_check <user_id>: Check user's signature information
Automated database backup system with scheduled and manual backup capabilities.
Features:
- Automated backups every 6 hours (0:00, 6:00, 12:00, 18:00)
- Backup rotation maintaining latest 20 backups with automatic cleanup
- Manual backup capability for immediate backup needs
- Backup limit management to prevent storage overflow
Commands:
/backup_now: Create an immediate backup file manually
Comprehensive giveaway management system with activity-based entry restrictions.
Features:
- Activity-count entry requirements for reaction, message, and voice time thresholds
- Time-based giveaway management with flexible duration formats
- Winner selection system with configurable winner counts
- Archive system preserving original giveaway information
- Modal draft flow for prize details, duration, provider, entry restrictions, and optional prize images
- Embed-based public panel with bot avatar thumbnail, optional prize image, persistent join button, and personal join/leave feedback
Commands:
/ga_create: Open the giveaway draft flow. Basic details, entry requirements, and optional image upload are configured from the draft controls./ga_cancel <giveaway_id>: Cancel active giveaway/ga_end <giveaway_id>: End giveaway early and select winners/ga_time_extend <giveaway_id> <time>: Extend giveaway duration/ga_participant <giveaway_id>: List all giveaway participants/ga_description <giveaway_id> <description>: Update giveaway description/ga_sendtowinner <giveaway_id> <message>: Send message to giveaway winners
Real-time teamup information display system for organizing team activities.
Features:
- Real-time display board with automatic updates every 2 minutes
- Game type categorization for organized teamup information
- Automatic cleanup of expired invitations and invalid data
- Discord integration with native time formatting and channel links
Commands:
/teamup_init <channel>: Create teamup display board in specified channel/teamup_type_add <channel> <game_type>: Add game type configuration/teamup_type_delete [channel] [channel_id]: Delete game type configuration. Use channel selection or channel ID (for deleted channels)./teamup_type_list: View all game type configurations
🆕 Recommended ticket system using Discord's native thread architecture for enhanced performance and user experience.
Key Features:
- Thread-based tickets leveraging Discord's native functionality
- Modal confirmations preventing accidental ticket creation
- Dynamic button states that update based on ticket status (pending/accepted/closed)
- Comprehensive admin system with type-specific and global permissions
- Automatic admin notifications via DM with jump buttons
- Persistent state management surviving bot restarts
- Statistics and analytics for ticket system monitoring
- Automatic cleanup for tickets with missing channels on startup
- Public initialization feedback from
/tickets_initso setup status is visible in-channel
Admin Management:
- Type-specific permissions allowing different admins for different ticket types
- Global admin system for overall ticket management
- Automatic admin addition to ticket threads with rate limiting
- Permission inheritance from Discord roles and individual user assignments
Commands:
/tickets_init: Initialize the new ticket system/tickets_stats: Display comprehensive ticket statistics/tickets_admin_list: Show current admin configuration/tickets_admin_add_role <role>: Add admin role with type selection/tickets_admin_remove_role <role>: Remove admin role from system/tickets_admin_add_user <user>: Add individual admin user/tickets_admin_remove_user <user>: Remove individual admin user/tickets_add_user <user>: Add user to current ticket/tickets_accept: Accept current ticket (admin only)/tickets_close <reason>: Close current ticket with reason/tickets_refresh_buttons: Refresh all ticket button states/tickets_refresh_main: Refresh main ticket creation page/tickets_add_type: Add a ticket type shown on the main panel/tickets_edit_type: Edit a ticket type's metadata, guide, button color, or admins/tickets_delete_type: Delete a ticket type and refresh the main panel
User Experience:
- Jump buttons for easy navigation to ticket threads
- Rich embeds with comprehensive ticket information
- Button state indicators showing ticket status at a glance
- Modal confirmations for important actions
🔥 Enhanced point-based economy system with makeup check-in functionality and improved user experience.
Core Features:
- Balance management with point tracking and transfer capabilities
- Daily check-in system with streak bonuses and reward tracking
- Advanced makeup check-in system for missed days (NEW in v1.7.1b)
- Transaction history with detailed logging and monthly views
- Admin controls for manual balance adjustments with audit trails
- Check-in streaks encouraging daily engagement with accurate tracking
🆕 Makeup Check-in System:
- Monthly limit: 3 makeup check-ins per month with intelligent quota management
- Smart validation: Prevents makeup before first manual check-in
- Cost-based system: 20 points per makeup (configurable) vs 10 points earned per check-in
- Automatic streak recalculation ensuring accurate statistics after makeup
- Comprehensive UI showing remaining quotas and streak information
Interactive Check-in System: The new check-in system is completely interface-based using interactive embeds with buttons:
- ✅ Daily Check-in Button: Perform daily check-in to earn points (must be in voice channel)
- ⏰ Makeup Check-in Button: Make up for missed check-in days (costs 20 points, 3 times per month)
- 🔍 Query Button: View personal check-in status and history
Commands:
/create_checkin_embed <channel>: (Admin) Create interactive check-in panel in specified channel/checkin_history <user>: (Admin) View comprehensive check-in details for a specific user/balance_change <user>: (Admin) Modify user balance with detailed forms/balance_history [user]: View transaction history with pagination
🏠 Enhanced private voice channel system with flexible purchasing and restoration capabilities.
Core Features:
- Temporary ownership system with configurable expiration periods (32 days default)
- Point-based purchasing integrated with shop system and voice activity discounts
- Activity-based discounts rewarding active voice users (up to 100% off)
- Room restoration for accidentally deleted channels within validity period
- Automatic cleanup of expired rooms with smart scheduling
- Renewal reminder system with automated DM notifications when rooms approach expiration
Enhanced User Experience:
- Purchase and restoration options: Buy new rooms or restore existing ones
- Seamless room creation with proper room information messages
- Voice activity rewards encouraging engagement with discount system
- Automatic notifications via DM for expiration and renewal opportunities
Commands:
/privateroom_init: (Admin) Initialize private room system with settings table/privateroom_setup <channel>: (Admin) Configure private room shop interface/privateroom_reset: (Admin) Reset entire private room system/privateroom_list: List all active private rooms with pagination/privateroom_ban <user>: (Admin) Ban user from private room system/privateroom_fix <user> <days>: (Admin) Repair an active private room's expiration state
Shop Interface:
- 🛍️ Purchase Button: Buy new private room with intelligent settings detection
- 🔄 Restore Button: Restore previously owned room if available within validity period
- ⚙️ Smart Settings Choice: Automatically detects saved settings and offers restoration options
Advanced Dungeons & Dragons dice rolling system with comprehensive notation support.
Features:
- Advanced dice notation supporting complex expressions (3+4d6, 2d04 for 0-4 range)
- Multiple roll support with detailed breakdown of each roll
- Zero-inclusive dice (d06 for 0-6 range vs d6 for 1-6 range)
- Batch rolling with expression-based repetition (5#3+4d6)
- Table format results for easy reading
Commands:
/dnd_roll <expression> [x]: Roll dice using DnD notation- Examples:
3+4d6(roll 4 six-sided dice and add 3) d02(roll 0-2 inclusive die)5#3+4d6(repeat3+4d6roll 5 times)- Parameter
xspecifies repetition count (overridden by#in expression)
- Examples:
Interactive spy-based team game system for voice channel activities.
Features:
- Team formation system with button-based signup
- Voice channel validation ensuring participants are in voice
- Spy randomization with secret DM notifications
- Multi-stage game flow from setup to reveal
- Interactive buttons for team management and game control
Commands:
/spymode <team_size> <spy>: Create spy mode game with specified team size and spy count- Example:
/spymode 5 1creates 5v5 teams with 1 spy per team
- Example:
Game Flow:
- Setup Phase: Define team sizes and spy counts
- Registration Phase: Players join teams via buttons
- Game Start: Spy assignments sent via DM
- Reveal Phase: Show spy identities to all participants
🔨 Comprehensive moderation system providing ban, tempban, and mute functionality with automated management.
Key Features:
- Permanent bans with configurable message deletion periods
- Temporary bans with automatic unban scheduling and DM notifications
- Mute system using Discord's native timeout feature (up to 28 days)
- Admin permission system with role and user-based access control
- Notification system with customizable channel alerts
- Automatic recovery of active tempbans after bot restart
Enhanced Functionality:
- Duration parsing supporting multiple formats (1m, 1h, 1d, 1w)
- Database persistence for tempban tracking and recovery
- User DM notifications with server rejoin links for tempbans
- Rich embed notifications with user avatars and timestamps
- Comprehensive admin management with role and user assignment
Commands:
/ban <user> <reason> [delete_message_days]: Permanently ban a user/tempban <user> <duration> <reason> [delete_message_days]: Temporarily ban a user/mute <user> <duration> <reason>: Mute a user using Discord timeout/ban_list_tempbans: List all active temporary bans in the server/ban_admin_list: Display current admin permissions and settings/ban_admin_add_role <role>: Add role to ban admin permissions/ban_admin_delete_role <role>: Remove role from ban admin permissions/ban_admin_add_user <user>: Add user to ban admin permissions/ban_admin_delete_user <user>: Remove user from ban admin permissions/ban_set_notification_channel <channel>: Set ban notification channel/ban_remove_notification_channel: Remove ban notification channel/ban_set_invite_link <invite_link>: Set rejoin link for tempbanned users/ban_remove_invite_link: Remove rejoin link setting
RatingCog, NotebookCog, and the old channel-based TicketsCog are removed from runtime. They should not appear in Discord command picker, active config templates, or active test flows.
Old implementation snapshots and sanitized legacy templates live on the legacy-old-files-archive branch. See LEGACY_ARCHIVE.md on main and LEGACY_ARCHIVE_INDEX.md on that branch.
YAML-based configuration singleton with lazy loading, caching, and i18n.
- YAML-first (ruamel.yaml round-trip): per-cog
bot/config/<name>.yaml; comments survive writes. - Atomic writes via sibling tempfile +
os.replace(crash-safe). - i18n locale loader via
get_locale(name, lang)readingbot/locales/<lang>/<name>.yaml;bot.utils.i18n.t(...)is the call-site helper. - Text split: user-facing UI text should be in locale YAML; runtime YAML keeps IDs, paths, colours, limits, prices, and content metadata.
welcome_textremains in config because it can embed deployment-specific Discord URLs/custom emoji IDs. - Lazy loading with in-memory cache;
reload_config/reload_localefor runtime refresh.
Unified validation system supporting both Context and Interaction objects.
- Admin channel validation for command restrictions
- Voice state checking utilities for voice-dependent features
- Flexible validation supporting multiple Discord API patterns
Comprehensive database manager for the thread-based ticket system (renamed from tickets_new_db in P1-3c).
- Thread-based ticket management with full CRUD operations
- Member tracking with addition timestamps and relationship management
- Statistics collection for reporting and analytics
- Configuration storage in database for dynamic updates
Enhanced file operations module with advanced capabilities.
- Directory tree generation for archive organization
- File size validation before processing
- Automatic cleanup of temporary files
- Archive creation with compression support
Media processing module with validation and security features.
- File size validation before download with configurable limits
- Hash-based file naming preventing conflicts and duplicates
- Automatic directory creation for organized storage
- Size limit enforcement for resource management
🔥 Enhanced database integration module for the comprehensive economy system.
- Transaction tracking with detailed logging and categorization
- Balance management with comprehensive audit trails
- Advanced check-in streak tracking with makeup support and accurate recalculation
- Makeup check-in management with monthly quota tracking and intelligent validation
- Monthly statistics generation for reporting and analytics
- First check-in tracking for makeup validation and user progress monitoring
🏠 Enhanced database manager for the private voice channel system.
- Room ownership tracking with comprehensive expiration management
- Purchase history with pricing calculations and discount tracking
- Activity-based discount calculations for user engagement rewards
- Automatic cleanup of expired room data with configurable retention
- Shop message management for purchase interface persistence
🏆 Comprehensive achievement tracking database manager for user progress monitoring.
- Multi-category achievement tracking for messages, reactions, voice time, and check-ins
- Monthly statistics system with separate tracking for monthly achievements
- Voice session management with start/stop tracking and time calculation
- Leaderboard generation with ranking and extended leaderboard support
- Manual operation logging for admin adjustments with audit trails
- Checkin integration with shop system for total and streak-based achievements
🎭 Role assignment database manager for interactive role systems.
- View persistence management for role selection interfaces across different types
- Achievement progress queries with unified data retrieval from multiple sources
- Signature system management with time-slot based change tracking and cooldowns
- Voice time requirement checking for signature permissions
- Permission management with user signature enable/disable functionality
- Database operations for role views, star sign, MBTI, gender, and signature systems
🔨 Comprehensive moderation database manager for the ban system.
- Tempban tracking with automatic expiration management
- Ban history storage with detailed logging and timestamps
- Active tempban recovery ensuring continuity after bot restarts
- Database cleanup of expired records with configurable retention
- Admin permission persistence with role and user tracking
- Main functionality should be placed in the
bot/directory - Deprecated or removed code should normally rely on git history instead of staying in main.
- Old archived material lives on the
legacy-old-files-archivebranch. SeeLEGACY_ARCHIVE.mdon main andLEGACY_ARCHIVE_INDEX.mdon that branch.
- Keep runtime code in
bot/and reusable tests intests/. - Do not force-add real legacy configs or local scratch files.
- Update documentation to reflect code organization changes
- Use
bot.utils.fmt_user,fmt_channel, andfmt_rolewhen logging Discord users, channels, threads, or roles. - The standard log shape is
name (id)for channels/roles anddisplay_name / username (id)for users when those names differ. Raw IDs are logged asunknown (id)when no cached Discord object is available. Numeric IDs use ASCII parentheses.
This repository is the generic upstream. A production server clones it, fills in real bot/config/*.yaml from the *.yaml.example templates (gitignored), and may further customize locale text under bot/locales/ and images under resources/images/ for its own community. Those server-local edits are expected — treat the repo copies as defaults, and never assume a production checkout is clean.
Upgrading a deployment:
- Back up
data/bot.db(and the DB key file for encrypted deployments). git stash— preserves server-local locale/image edits.git pullgit stash pop— resolve conflicts keeping the server-side text where intended.- Re-sync dependencies if the lockfile changed, then restart the bot. DB schema migrations run automatically at startup.
Do not run git checkout -- . or git reset --hard on a production box; both destroy the server-local content customizations.
See PRIVACY.md for the data inventory, privileged-intent rationale, log/backup retention notes, and SQLCipher database encryption procedure.
- Added
InviteGuard_Cogto silently clean active Discord invites older than the configured retention window. - Added dry-run support, invite-code and creator whitelists, scheduled cleanup, and logging summaries.
- Added invite attribution storage and a Components v2 invite leaderboard panel with Top 15 ranking, viewer-local relative update time, bot avatar thumbnail, and
/invite_sync,/invite_check_user,/invite_create_embedoperator commands. - Added configurable invite rewards through the Shop balance system: each newly counted valid invite awards
reward_points_per_invitepoints, defaulting to 60. - Added pooled invite attribution with batch settlement: same-window joins settle together, inviters are credited and rewarded when the total invite-use delta matches the batch size, and invite cache access is serialized against the background sync.
- Added a reward notification DM to the inviter with a Components v2 layout, reward image, and a leaderboard link button jumping to the panel message; active only while a valid leaderboard panel exists.
- Documented required Discord invite permissions and the project convention that default owner/admin command access maps to
main.admin_channel_id.
- Completed the config 2.0 runtime migration: YAML configuration, locale-backed UI text, package-based cogs, and DB-backed mutable feature data are now the active runtime path.
- Removed runtime registration for legacy NotebookCog, RatingCog, and the old channel-based TicketsCog; archived historical code on
legacy-old-files-archive. - Added fake Discord interaction flow tests for the retained modules, covering local handler behavior without requiring live Discord.
- Improved PrivateRoom renewal semantics so stale active rooms renew from the current time instead of charging users for already-expired days.
- Standardized Discord entity logging with name and ID formatting for users, channels, roles, and guilds.
- Added migration tooling for pre-config-2.0 JSON deployments and expanded public YAML template documentation.
- Retired giveaway-related achievement categories while keeping GiveawayCog itself active.
- Locked the Python runtime and dependency environment with
.python-versionand the project lock files. - Added preflight role validation before creating achievement, star sign, MBTI, and gender pickup panels.
- Allowed optional starter roles in
Role_Cogso emptyachievement_start_role_idandsocial_start_role_idno longer crash role assignment flows. - Hid feature-linked achievement content when the related module is disabled.
- Changed
/tickets_initfollow-up messages to public responses instead of only-visible-to-user replies. - Fixed
VoiceStateCogstartup ordering sotemp_channelsis created or migrated before cleanup tasks run. - Updated
BanCogtask creation toasyncio.create_task(...)for current runtime compatibility and cleaner task cleanup.
From V1.4.0b
- Added feature toggles in
config_main.jsonfor per-module loading. - Disabled modules, or modules without config, are now skipped cleanly without startup errors.
- Commands for skipped modules are no longer registered.
- Private Room System:
- Fixed an issue that previously allowed users to infinitely renew private rooms under specific conditions.
- If the user has disabled DMs, the bot will now send a reminder in the private room that could be renewed.
- Extend the makeup signup application window to 180 days
- Optimised behaviour for full party composition: Removed synchronisation buttons and bottom prompts for existing parties or when full, preventing residual information from causing disruption.
- Enhanced
/print_voice_status: Highlight daily/monthly peaks, display yearly data as monthly bar charts, and optimised date axis and annotation styles. - Slash command synchronisation fixes: Eliminated duplicate guild-level synchronisation; duplicate commands no longer appear after restarting or executing
/synccommands.
- Private Room System: Fixed critical error preventing room creation
- Cleaned up unused database methods and tables
- Command Sync: Now all commands will automatically sync with the bot
- Room Activity Logging System: Separate log file for room-related activities
- Control panel creation and teamup cleanup events
- Private Room Renewal Reminders: Automated DM notifications for expiring rooms
- Check Log Command Refactor: Simplified parameter system
- Dropdown selection for log types (main/keyword/room)
- Database Migration Cleanup: Removed legacy compatibility code
- Streamlined database initialization
- Voice Room Control Panel: Interactive control panel in voice channels
- 4-button interface for room management (unlock, lock, full, soundboard)
- Direct room type switching without commands
- Dynamic color-coded embeds based on room type
- Auto-recovery system after bot restart
- Teamup Auto-Full System: Automatic marking of previous teamup messages as full when new messages are sent
- Database tracking of teamup message IDs
- Non-blocking async processing for smooth user experience
- New check-in system
- Embed interface based system, easier to use
- Daily check-in automatic refresh
- All commands related to channel selection have been reworked, replacing channel IDs with a more modern and user-friendly selection list.
- Improved user experience with Discord's native channel selection interface
- Enhanced remove/delete commands with hybrid parameters (channel selection + manual ID for deleted channels)
- Fixed an issue where room creation failed due to user IDs being blocked by Discord.
- Completely removed old ticket system (
tickets_cog.py) and migration functionality - Added automatic cleanup of tickets with missing channels
- Fixed an issue with ticket permissions, which now correctly uses private tickets.
- Fixed the archiving function for old tickets. Now you can conveniently archive old tickets with one click.
- Added a temporary command to convert non-private tickets in the new version to private tickets.
- Quick fix for the achievement check crash when there are too many achievements.
- Reconstructed the achievement cog and role cog. Used a more advanced database and logic separation architecture.
- Support for achievements related to total check-ins and consecutive check-ins has been created.
- Fixed an issue where the ‘Accept’ button displayed an incorrect status in closed tickets.
-
TeamupDisplay System Fixes:
- Optimised the display of the teamup dashboard and blocked the display of the @ section.
-
Old Tickets System:
- Restored the
/tickets_archivecommand to archive all tickets.
- Restored the
- TeamupDisplay System Implementation: Added comprehensive
TeamupDisplay_Cogwith real-time team organization capabilities- Real-time display board with automatic updates every 2 minutes
- Game type categorization for organized teamup information
- Automatic cleanup of expired invitations and invalid data
- Discord integration with native time formatting and channel links
- Rating System Removal: Completely removed
Rating_Cogfunctionality- All rating-related commands and features have been discontinued
- Rating data will be preserved in database but no longer accessible through bot commands
- Ban System Fixes:
- Fixed database unique errors
- Fixed ban logging issues
- Tempban System Fixes: Resolved major issues with temporary ban management
- Fixed automatic unban logic that wasn't processing expired tempbans correctly
- Administrative Tools:
/ban_list_tempbans- View all active temporary bans in the server- Improved startup logic with better expired tempban processing
- Ban System Implementation: Added comprehensive
Ban_Cogwith moderation capabilities- Permanent ban functionality with configurable message deletion
- Temporary ban system with automatic unban scheduling
- Mute system using Discord's native timeout feature
- Advanced admin permission management with roles and users
- Rich notification system with channel alerts and user DMs
- Database persistence and automatic recovery after restarts
- Tickets System Update: Modified command structure in new ticket system
- Updated command names and functionality for better user experience
- Enhanced thread-based ticket management
- Legacy Tickets Deprecation: Old
Tickets_Cogmarked as deprecated- Legacy system will be removed in future versions
- Users should migrate to
Tickets_New_Cogfor continued support
- Fixed an issue with close ticket number display in the new ticket system.
- Private room system extend
- Users can now extend their private rooms by one month in advance.
- Check In make up
- Users can now spend a certain number of points each month to make up for three missed sign-ins.
-
Complete Ticket System Overhaul: Introduced
Tickets_New_Cogwith thread-based architecture- Thread-based tickets using Discord's native functionality
- Modal confirmations for ticket creation
- Dynamic button states with persistent management
- Comprehensive admin system with type-specific permissions
- Automatic DM notifications with jump buttons
- Rate-limited admin addition to prevent API limits
-
Dual Logging System: Implemented separate logging for main application and keyword detection
- Main application logs:
./data/bot.log - Keyword detection logs:
./data/keyword_detection.log - Enhanced
/check_logcommand withkeyword_logparameter - UTF-8 encoding support and configurable log paths
- Main application logs: