Combusken Bot - Pokémon Draft Tournament Manager

A Discord bot for managing Pokémon draft tournaments with Google Sheets integration.

Features

• Read tournament format metadata from Google Sheets
• Automatically create Discord channels and roles for tournaments
• Interactive draft system with dropdown menus
• Pick validation and Google Sheets updates
• Tournament state management

Setup

1. Install Dependencies

pip install -r requirements.txt

2. Discord Bot Setup

1. Go to Discord Developer Portal
2. Create a new application
3. Go to the "Bot" section and create a bot
4. Copy the bot token
5. Enable the following bot permissions:
   • Read Messages/View Channels
   • Send Messages
   • Manage Channels
   • Manage Roles
   • Use Slash Commands
   • Read Message History
6. Invite the bot to your server with the appropriate permissions

3. Google Sheets API Setup

You have two options for authentication:

Option A: Service Account (Recommended for Bots)

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API
4. Go to "Credentials" → "Create Credentials" → "Service Account"
5. Create a service account and download the JSON key file
6. Save the JSON file as credentials.json in the project root
7. Share your Google Sheet with the service account email (found in the JSON file)

Option B: OAuth 2.0

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Sheets API
4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
5. Choose "Desktop app" as the application type
6. Download the credentials and save as credentials.json
7. Run the OAuth setup script:

   python setup_oauth.py

8. This will open a browser window for authentication
9. After authentication, a token.json file will be created

4. Environment Configuration

Create a .env file in the project root:

DISCORD_BOT_TOKEN=your_discord_bot_token_here
GOOGLE_SHEETS_ID=your_google_sheet_id_here
GOOGLE_CREDENTIALS_FILE=credentials.json
TOURNAMENT_ROLE_PREFIX=Tournament
DRAFT_CHANNEL_NAME=draft

To find your Google Sheet ID:

• Open your Google Sheet
• Look at the URL: https://docs.google.com/spreadsheets/d/SHEET_ID_HERE/edit
• The SHEET_ID_HERE is what you need

5. Google Sheet Configuration

Your Google Sheet should have at least two sheets:

Format Sheet (default name: "Format")

Contains the list of available Pokémon with headers in the first row:

Name	Tier	...
Charizard	OU	...
Pikachu	OU	...

• First row must contain headers (Name, Tier, etc.)
• Each subsequent row is a Pokémon
• The "Name" column is required

Draft Picks Sheet (default name: "Draft Picks")

This sheet will be auto-created with headers if it doesn't exist:

• User
• Pokemon
• Round
• Pick
• Timestamp

6. Run the Bot

python bot.py

Commands

User Commands

• !draft [pokemon] - Draft a Pokémon

  • Without arguments: Opens a dropdown menu to select from available Pokémon
  • With argument: Directly drafts the specified Pokémon (e.g., !draft Charizard)
  • Only works when it's your turn to draft

• !status - View current draft status

  • Shows current round, pick number, recent picks, and who's up next

Admin Commands

• !setup - Set up tournament channels and roles

  • Creates a draft channel (default name: "draft")
  • Creates a tournament participant role

• !startdraft [@user1] [@user2] ... - Start a new draft

  • Specify participants by mentioning them
  • If no participants are specified, uses members with the tournament role
  • Requires at least 2 participants
  • Example: !startdraft @Player1 @Player2 @Player3

Draft Flow

1. Admin runs !setup to create channels and roles
2. Admin adds participants to the tournament role (or mentions them in !startdraft)
3. Admin runs !startdraft to begin the draft
4. Players use !draft when it's their turn
5. The bot validates picks, updates Google Sheets, and announces selections
6. Draft continues in snake format until all rounds are complete

Troubleshooting

• "Google Sheets is not configured": Check that GOOGLE_SHEETS_ID is set in .env and credentials.json exists
• "Unable to authenticate": Ensure your credentials file is valid and the sheet is shared with the service account (if using service account)
• "No active draft": Run !startdraft first
• "It's not your turn": Wait for your turn in the draft order