Event Bot for Discord

A Discord bot that automatically creates voice channels for events, posts announcements, and manages event lifecycle.

---

Table of Contents

1. What Does This Bot Do?
2. Requirements
3. Setup Guide (Step by Step)
4. Configuration Explained
5. Commands
6. How Events Work
7. Features
8. Troubleshooting

---

What Does This Bot Do?

This bot automates event hosting on your Discord server:

1. Someone joins a "lobby" voice channel - This triggers the bot
2. Bot picks an event - Either randomly or lets the user choose via DM
3. Bot creates a voice channel - Named after the event
4. Bot posts an announcement - With event details, image, and a "Join" button
5. Bot pings a role - So people know an event is starting
6. When everyone leaves - The voice channel is deleted and the event ends

It's like having an automated event manager that handles all the boring stuff.

---

Requirements

• Python 3.8 or higher - Download from python.org
• A Discord Bot Token - You'll create this on the Discord Developer Portal
• A Discord Server - Where you have admin permissions

---

Setup Guide (Step by Step)

Step 1: Create a Discord Bot

1. Go to the Discord Developer Portal
2. Click "New Application" (top right)
3. Give it a name (like "Event Bot") and click Create
4. Go to the "Bot" tab on the left sidebar
5. Click "Reset Token" and copy the token - SAVE THIS SOMEWHERE SAFE
6. Scroll down and enable these Privileged Gateway Intents:
   • SERVER MEMBERS INTENT - ON
   • MESSAGE CONTENT INTENT - ON

Step 2: Invite the Bot to Your Server

1. Still in the Developer Portal, go to "OAuth2" > "URL Generator"
2. Under SCOPES, check:
   • bot
   • applications.commands
3. Under BOT PERMISSIONS, check:
   • Manage Channels
   • Send Messages
   • Embed Links
   • Attach Files
   • Read Message History
   • Mention Everyone
   • Move Members
   • Connect
   • Manage Roles (for channel permissions)
4. Copy the generated URL at the bottom
5. Paste it in your browser and select your server

Step 3: Get Your Server IDs

You need to enable Developer Mode in Discord to copy IDs:

1. Open Discord Settings (gear icon)
2. Go to "Advanced"
3. Turn on "Developer Mode"

Now you can right-click on things and select "Copy ID":

• Server ID: Right-click your server name > Copy Server ID
• Channel IDs: Right-click a channel > Copy Channel ID
• Role IDs: Server Settings > Roles > Right-click a role > Copy Role ID

Step 4: Configure the Bot

1. Open config.yaml in a text editor (Notepad, VS Code, etc.)
2. Fill in your values:

bot:
  token: "PASTE_YOUR_BOT_TOKEN_HERE"

server:
  guild_id: 123456789012345678  # Your server ID
  lobby_channel_id: 123456789012345678  # Voice channel that triggers events
  announcement_channel_id: 123456789012345678  # Text channel for announcements
  config_editor_channel_id: 123456789012345678  # Admin channel for live config editing

settings:
  max_concurrent_events: 1  # How many events can run at once
  cooldown_seconds: 300  # Seconds between events (300 = 5 minutes)
  generated_vc_user_limit: 0  # Max users in event VC (0 = unlimited)
  pm_selection_mode: false  # false = random event, true = user picks via DM
  pm_selection_timeout: 60  # Seconds to wait for DM response
  auto_cleanup: false  # If true, deletes event embeds when event ends
  admin_role_ids:
    - 123456789012345678  # Role ID that can use admin commands

events:
  - name: "Your Event Name"
    description: "What this event is about"
    role_id: 123456789012345678  # Role to ping when this event starts
    color: "#FFD700"  # Hex color for the embed
    images:
      - "./images/your_image.jpg"  # Local image in images folder

Step 5: Add Your Images

1. Put your event images in the images folder
2. Reference them in config as ./images/filename.jpg
3. Supported formats: JPG, PNG, GIF, WEBP

Step 6: Install Dependencies

Open a terminal/command prompt in the bot folder and run:

pip install -r requirements.txt

Step 7: Run the Bot

python bot.py

You should see:

[INFO] Bot logged in as YourBotName#1234
[INFO] Slash commands synced!
[INFO] Bot is ready!

---

Configuration Explained

Bot Section

bot:
  token: "YOUR_TOKEN_HERE"

Your bot's secret token. NEVER share this with anyone!

Server Section

server:
  guild_id: 123456789012345678
  lobby_channel_id: 123456789012345678
  announcement_channel_id: 123456789012345678
  config_editor_channel_id: 123456789012345678

Setting	What It Does
guild_id	Your Discord server's ID
lobby_channel_id	The voice channel users join to start an event
announcement_channel_id	Text channel where event announcements are posted
config_editor_channel_id	Text channel where admins can edit config live (optional)

Settings Section

settings:
  max_concurrent_events: 1
  cooldown_seconds: 300
  generated_vc_user_limit: 0
  pm_selection_mode: false
  pm_selection_timeout: 60
  auto_cleanup: false
  admin_role_ids:
    - 123456789012345678

Setting	What It Does
max_concurrent_events	How many events can run at the same time
cooldown_seconds	Wait time between events (prevents spam)
generated_vc_user_limit	Max users in event voice channel (0 = unlimited)
pm_selection_mode	false = random event, true = user chooses via DM
pm_selection_timeout	How long to wait for DM response before canceling
auto_cleanup	false = post "Event Ended" embed, true = delete embed entirely
admin_role_ids	List of role IDs that can use admin commands

Events Section

events:
  - name: "Event Name"
    description: "Event description"
    role_id: 123456789012345678
    color: "#FFD700"
    images:
      - "./images/image1.jpg"
      - "./images/image2.jpg"

Setting	What It Does
name	The event's display name
description	Text shown in the announcement embed
role_id	Which role gets pinged when this event starts
color	Hex color code for the embed sidebar (like #FF0000 for red)
images	List of images - one is randomly picked per event

Adding More Events: Just copy the event block and paste it below!

events:
  - name: "Event One"
    description: "First event"
    role_id: 111111111111111111
    color: "#FF0000"
    images:
      - "./images/event1.jpg"

  - name: "Event Two"
    description: "Second event"
    role_id: 222222222222222222
    color: "#00FF00"
    images:
      - "./images/event2.jpg"

---

Commands

All commands are slash commands. Type / in Discord to see them.

For Everyone

Command	What It Does
/help	Shows all commands and how the bot works
/eventinfo	Shows currently active events

For Admins Only

Command	What It Does
/generateevent	Manually create an event (DMs you to pick which one)
/mode 1	Set to random selection mode (default)
/mode 2	Set to PM selection mode (user picks via DM)
/lockevent	Lock/unlock the lobby channel (prevents new events)

Note: Admin commands require your role to be listed in admin_role_ids in the config.

---

How Events Work

Starting an Event

Mode 1 - Random Selection (Default):

1. User joins the lobby voice channel
2. Bot picks a random event from the config
3. Event starts immediately

Mode 2 - PM Selection:

1. User joins the lobby voice channel
2. Bot sends them a DM with a dropdown menu
3. User picks which event they want to host
4. Event starts after selection

During an Event

1. A voice channel is created (named after the event)
2. The triggering user is moved to the new channel
3. An announcement is posted with:
   • Event name and description
   • A random image from that event's image list
   • "Join Event" button - moves clickers to the voice channel
   • "Create Team VCs" button - creates Team 1 and Team 2 channels

Ending an Event

1. When ALL users leave the event voice channel(s)
2. The voice channel(s) are deleted
3. The announcement is updated to show "Event Ended"
4. Cooldown timer starts

Team Voice Channels

When someone clicks "Create Team VCs":

• The main event channel is renamed to "Team 1"
• A new "Team 2" channel is created
• The event only ends when BOTH channels are empty
• Users can move between Team 1 and Team 2 without ending the event

---

Features

Live Config Editor

Admins can edit the bot configuration without restarting:

1. Go to your config editor channel
2. Paste YAML configuration (with or without ```yaml code blocks)
3. Bot validates and applies the changes
4. A preview embed shows the current config

Important:

• The bot token is hidden in the preview (shows as ***HIDDEN***)
• You cannot change the token via Discord (security feature)
• Your message is deleted immediately after processing

Cooldown System

Prevents event spam:

• After an event starts, new events are blocked for X seconds
• Users who try to start events during cooldown get a DM explaining the wait time
• Admins using /generateevent bypass the cooldown

Race Condition Protection

If multiple people join the lobby at the exact same time:

• Only the first person triggers an event
• Others get a message saying "An event is already being created"
• No duplicate events or DM spam

Lobby Lock

Admins can lock/unlock the lobby channel:

• /lockevent toggles the lock
• When locked, users can't join the lobby (prevents all events)
• Useful for maintenance or scheduled downtime

---

Troubleshooting

Bot won't start

"Please set your bot token in config.yaml!"

• You forgot to add your bot token, or it's still set to the placeholder

Token is invalid

• Go back to the Discord Developer Portal and reset your token
• Copy the new token carefully (no extra spaces)

Slash commands don't appear

Wait a minute - Discord can take up to an hour to sync commands globally

Check bot permissions:

• Make sure you invited the bot with applications.commands scope
• Re-invite the bot using the URL from Step 2

Bot doesn't respond to lobby joins

Check your channel ID:

• Make sure lobby_channel_id is a VOICE channel, not a text channel
• Verify the ID is correct (right-click > Copy ID)

Check the logs:

• The bot logs to eventbot.log and console
• Look for "Voice state update" messages

"I don't have permission" errors

The bot needs these permissions:

• Manage Channels - to create/delete voice channels
• Move Members - to move users to event channels
• Send Messages - to post announcements
• Embed Links - to send rich embeds
• Attach Files - to send local images
• Mention Everyone - to ping roles

Images not showing

For local images:

• Make sure the file exists in the images folder
• Check the path in config (should be ./images/filename.jpg)
• File names are case-sensitive on some systems

For URL images:

• Make sure the URL is a direct link to an image
• The URL must be publicly accessible

Config editor not working

"You don't have permission"

• Your role isn't in admin_role_ids
• Add your role ID to the config

YAML errors

• Check your YAML syntax (indentation matters!)
• Use a YAML validator online to check for errors

Multiple config preview messages

• Delete the old preview messages manually
• The bot will now track and update a single preview message

---

File Structure

eventbot/
├── bot.py              # Main bot code
├── config.yaml         # Your configuration
├── requirements.txt    # Python dependencies
├── eventbot.log        # Log file (created when bot runs)
├── README.md           # This file
└── images/             # Your event images
    ├── image1.jpg
    ├── image2.jpg
    └── ...

---

Need Help?

If you're stuck:

1. Check the eventbot.log file for error messages
2. Make sure all IDs in config are correct
3. Verify the bot has all required permissions
4. Restart the bot after config changes (unless using live editor)

---

Quick Reference

What You Want	How To Do It
Start an event	Join the lobby voice channel
Choose which event	Set pm_selection_mode: true in config or use /mode 2
Add more events	Copy an event block in config and edit it
Change cooldown	Edit cooldown_seconds in config
Stop all events	Use /lockevent to lock the lobby
See active events	Use /eventinfo
Edit config live	Paste YAML in the config editor channel