Remaining7 Discord Bot

Overview

Name: Remaining7 Discord Bot Version: v1.7.5 Contributors: remainingdelta, nightwarrior5 Objective: A feature-rich Discord bot for the Remaining7 community server (16k+ members). Handles an R7 Token economy, leveling, quests, a Brawl Stars collection minigame, tournament management with Matcherino integration, support tickets, event operations, a security protocol, and multi-language translation. Server Link: https://discord.gg/6MzrjS2X8k

---

Tech Stack

• Language: Python 3.10+
• Framework: discord.py (slash commands + prefix commands)
• Database: MongoDB Atlas via motor (async)
• Translation: deep-translator + langdetect
• External API: Matcherino (tournament brackets, payouts)
• Linting: Ruff (ruff check . / ruff format .)

---

Project Structure

Remaining7-Discord-Bot/
├── main.py                          # Entry point — loads cogs, syncs commands
├── requirements.txt
├── .env.example
├── .gitignore
├── CLAUDE.md
├── README.md
├── database/
│   └── mongo.py                     # All MongoDB helper functions
├── features/
│   ├── config.py                    # IDs, shop data, loot tables, emojis (REAL/TEST branches)
│   ├── economy.py                   # R7 Tokens, shop, daily, leveling, leaderboards
│   ├── quests.py                    # Daily & weekly quest system
│   ├── security.py                  # Hacked protocol (timeout, purge, flag)
│   ├── event.py                     # Event channel cleanup & reward payouts
│   ├── general.py                   # /help, /mod-help, /admin-help, /convert-time
│   ├── translation.py               # !t prefix & /translate slash command (55 languages)
│   ├── support_tickets.py           # General support tickets (issues, support, apps, partnership)
│   ├── ticket_command_router.py     # Shared routing for tourney & support ticket commands
│   ├── brawl/
│   │   ├── brawlers.json            # Brawler data (name, rarity, gadgets, star powers, hypercharges)
│   │   ├── brawlers.py              # Brawler dataclass definitions
│   │   ├── commands.py              # /megabox, /starrdrop, /profile, /upgrade, etc.
│   │   └── drops.py                 # Weighted RNG drop logic
│   └── tourney/
│       ├── tourney_commands.py      # All tournament slash & prefix commands
│       ├── tourney_utils.py         # Ticket lifecycle helpers, auto-translation
│       ├── tourney_views.py         # discord.ui.View classes for ticket buttons
│       └── matcherino.py            # Matcherino API integration
└── .github/
    ├── ISSUE_TEMPLATE/
    │   ├── bug.md
    │   ├── enhancement.md
    │   └── feature.md
    └── workflows/
        └── lint.yml                 # Ruff linting CI

---

Core Features

R7 Token Economy

• Passive Income: Users earn 2–5 R7 Tokens per message (20-second cooldown). Server Boosters get a 2% average bonus.
• Daily Rewards: /daily grants 80–160 tokens (scaled by level). Requires 5 messages sent since last claim and a 24-hour cooldown.
• Supply Drop: /drop <amount> (Admin) to force a token drop in general chat.
• Balance & Ranking: /balance [user], /leaderboard [page].
• Give & Set: /give <user> <token/xp/level> <amount>, /set-balance <user> <amount> (Admin).
• Permissions: /perm <add/remove> <user> to grant/revoke command access.
• Guide: /economy-help for a full user-facing guide.

Shop & Budget System

• Browse: /shop lists items with prices and descriptions.
• Purchase: /buy <item> with dropdown selection and balance check.
• Redeem: /redeem <item> to claim a purchased reward.
• Monthly Cap: $50.00 monthly budget, auto-resets each calendar month.
• Budget Check: /check-budget shows spent vs. remaining.
• Budget Override: /set-budget <amount> (Admin).

Leveling & XP

• XP earned passively from messages alongside tokens.
• /level [user] — progress bar and next-level XP goal.
• /levels-leaderboard [page] — server-wide level rankings (paginated).

Quest System

• Daily Quests: 80 / 160 / 240 messages → 50–100 tokens + 200–300 XP.
• Weekly Quests: 500 / 750 / 1000 messages → 250–600 tokens + 1000–3000 XP.
• /quests — interactive progress bars for active quests.
• Quests auto-assign randomly; completion rewards are granted instantly.

Brawl Stars Collection Minigame

• Gacha Drops:
  • /megabox — open a Mega Box (coins, power points, brawlers, gadgets, star powers).
  • /starrdrop — open a Starr Drop with tiered rarity (Rare → Ultra Legendary).
• Collection:
  • /profile [user] — currencies, collection progress, stats.
  • /brawlers — paginated view of owned brawlers with levels.
  • /buy-brawler — purchase unowned brawlers by rarity using Credits.
• Progression:
  • /upgrade <brawler> — interactive upgrade dashboard (Level 1–11).
  • /buy-ability <brawler> — Gadgets (Lvl 7+), Star Powers (Lvl 9+), Hypercharges (Lvl 11+).
• Currencies: Coins, Power Points, Credits, Gems (separate from R7 Tokens).
• Rarities: Starting, Rare, Super Rare, Epic, Mythic, Legendary, Ultra Legendary, Chromatic.
• New users auto-receive Shelly at Level 1. Duplicate brawlers convert to Power Points.

Tournament System

• Phase Management:
  • !starttourney [region] — start live tournament, reset counters, init queue dashboard. Use !starttourney SA for South America mode.
  • !endtourney — end tournament, clean up dashboards and tickets.
• Ticket Panels: /tourney-panel (live) and /pre-tourney-panel (pre-tourney) post interactive open buttons.
• Ticket Operations:
  • !close / !c — close a ticket.
  • !lock / !unlock — lock/unlock a ticket channel.
  • !delete / !del — delete ticket with transcript.
  • !reopen — reopen a closed ticket.
  • /add <user> / /remove <user> — manage ticket access.
• Queue: /queue — check your position in line (inside a tourney ticket only).
• Queue Dashboard: Auto-updating embed every 15 seconds showing currently serving and queue length.
• Matcherino Integration:
  • /set-matcherino <id> — link active Matcherino bracket.
  • /match-info <match_id> — display roster for a specific match.
  • /match-history <team> — view match history.
  • /set-ticket-match <team1> <team2> — assign match context to a ticket.
  • /tourney-progress — bracket progress dashboard with semi-final/final announcements.
• Hall of Fame: /hall-of-fame — post winning teams with prize distribution.
• Blacklist: /blacklist add/remove/list — manage banned users (Discord ID, Matcherino profile, reason, alts).
• Rate Limits: Max 3 open tickets per user, 180s cooldown. Auto-reopen after 6-hour lock.
• Auto-translation: Ticket messages auto-translated via deep-translator + langdetect.
• Test Mode: /tourney-test-mode — toggle 100-ticket limit and 0.1s cooldown for testing.
• Staff Guide: /tourney-admin-help.
• SA Mode: South America region variant with separate ticket categories and region-specific workflow.

Tournament Admin Compensation

• /payout-add <users...> <amount> — record staff payouts (Split or Flat mode).
• /payout-list — view pending balances.
• /payout-history [page] — audit log of group payouts (filters out paid users).
• /payout-reset — clear a staff member's balance and archive receipts.

Support Tickets (Non-Tournament)

• /support-panel — post the master support ticket panel.
• Ticket Types:
  • Report an Issue — bugs, rule violations, technical problems.
  • Server Support — general server assistance.
  • Staff Application — apply for Tourney Admin or Event Staff.
  • Server Partnership — propose a partnership.
• One open ticket per type per user.
• Staff can close, reopen, and delete tickets with transcript generation.
• Transcripts DM'd to the opener and archived in a log channel.

Event Management

• Automated Monitoring: Daily background task at 12:00 AM ET scans event channels.
• Smart Alerts: Alert sent when messages are 7+ days old (prevents exceeding Discord's 14-day bulk-delete limit).
• Manual Cleanup: /clear-red, /clear-blue, /clear-green for instant channel wipes.
• Reward Payouts: /event-rewards <message_id> parses @User 500 format to batch-distribute tokens with confirmation.
• Staff Guide: /event-staff-help.

Security Protocol

• /hacked <user> [days] or !hacked (reply) — instantly timeout (7 days), flag in DB, purge messages across all channels.
• /unhacked <user> — remove flag and timeout.
• /hacked-list — view all currently flagged users.
• Logs to moderator logs channel. Prevents targeting equal/higher role members.

Translation

• !t [language] / !translate [language] — reply to a message to translate it to English.
• /translate <language> <phrase> — translate English text into any of 55 supported languages.
• Auto-detects source language. Google Translate backend.

Utility

• /convert-time <date> <time> <timezone> — convert a date and time to all Discord timestamp formats. Supports 20+ timezone aliases (EST, PT, GMT, etc.) and IANA names.

Help Commands

• /help — user command directory.
• /economy-help — full guide to earning and spending R7 Tokens.
• /mod-help — moderator guide (economy oversight, security protocol).
• /admin-help — admin manual (economy, events, security, tournaments, financials).
• /tourney-admin-help — tournament staff cheat sheet.
• /event-staff-help — event channel management guide.

---

Setup & Run Instructions

This bot requires Python 3.10+ and a MongoDB Atlas database.

1. Clone the Repository

   git clone https://github.com/RemainingDelta/Remaining7-Discord-Bot
   cd Remaining7-Discord-Bot

2. Setup Virtual Environment & Dependencies

   python -m venv venv
   source venv/bin/activate  # Linux/macOS
   # or venv\Scripts\activate on Windows
   pip install -r requirements.txt

3. Configure Environment Variables Copy .env.example to .env and fill in the values:

   BOT_MODE=DEV            # DEV (default) or PROD
   PROD_TOKEN=             # Production bot token (used when BOT_MODE=PROD)
   DEV_TOKEN=              # Dev/test bot token (used when BOT_MODE=DEV)
   MONGO_URI=              # MongoDB Atlas connection string
   

4. Update Configuration Verify and update IDs in features/config.py (channels, roles, categories, emojis) for your server. Both REAL and TEST branches must be maintained.

5. Run the Bot

   python main.py

   There is no test suite. Testing is done by running the bot with BOT_MODE=DEV against a test Discord server.

---

Database

Uses MongoDB database r7_bot_db with the following collections:

Collection	Purpose
users	Balance, XP, level, brawler collection, currencies, inventory
user_quests	Quest progress tracking (daily/weekly)
quests	Quest definitions
hacked_users	Flagged compromised accounts
blacklist	Tournament-banned users
payouts	Pending staff payouts
payout_logs	Payout batch audit logs
tourney_sessions	Active tournament session data
tourney_staff_stats	Staff performance metrics
support_ticket_counters	Ticket counters per type
settings	Global bot settings (budget, etc.)

---

Background Tasks

Task	Schedule	Description
Message listener	On every message	Passive token + XP generation (20s cooldown)
Quest tracker	On every message	Track quest progress, auto-complete and reward
Event cleanup	Daily at 12:00 AM ET	Scan event channels for stale messages
Queue dashboard	Every 15 seconds	Update tourney queue embed during live tournaments
Supply drop	Every 6 hours	Random token drop in general chat
Progress dashboard	Every 5 minutes (live)	Semi-final/final bracket announcements
Match refresher	Every 1 minute (live)	Refresh Matcherino scores in active tickets
Budget reset	On interaction	Auto-reset monthly redemption cap on month change

---

Permission Hierarchy

Role	Access
Admin	Full access to all commands
Moderator	Economy oversight, security protocol
Tourney Admin	Tournament commands, ticket management
Event Staff	Event channel cleanup, reward distribution
Member	Economy, quests, brawl, translation, help

---

Workflow

• Active development on dev branch.
• Feature/bug branches merge into dev via PR.
• dev merges into main for release.
• Ruff enforced via CI (.github/workflows/lint.yml).

---

Future Roadmap

• Brawl Stars: View for a specific brawler's details
• Giveaway system with extra entries via R7 Tokens