Twitch Bot Documentation

Complete feature list, command reference, and architecture overview.

1. Overview

A custom-built Twitch bot utilizing Python's twitchio library. It features a persistent SQLite database, interactive setup and message configuration scripts, automated OBS WebSocket controls, and local audio playback via Pygame.

2. Automated Features

XP & Leveling System

Awards XP to viewers at customized intervals defined in the bot's configuration. Users level up dynamically based on a linear XP scaling formula. Automated chat alerts trigger when active users or lurkers level up.

Stream Status Tracking

Checks if the stream is live every minute. If the stream remains offline for 2 consecutive checks, the bot automatically sends a goodbye message, creates a database backup, and initiates a safe shutdown.

Raid Handling

Detects incoming raids, drops a randomized welcome message containing the game the raider was playing, and grants the raider a 1-hour "Double XP" buff. Additionally, it triggers a "Raid Party Bonus," awarding 100 flat XP to everyone currently in chat.

Viewer Session Tracking

Silently monitors chatters every minute, tracking when they first joined and their total watch time for the current session. This data is automatically exported to a secure text file for analytics and moderation.

Utility Scripts

Includes a dedicated setup script for securely fetching and saving Twitch credentials to the environment file. It also features a Message Editor utility to easily update, add, or remove custom chat announcements without touching the raw JSON data. All scripts can be compiled into executables simultaneously using the provided batch file.

3. EventSub Integrations

OBS Hype Train System

  • Begin: Connects to OBS via WebSocket, unhides a designated scene source to play the video on stream, and awards the starter an instant level up.
  • Progress: Awards an instant level-up to any user who contributes to the train.
  • End: Hides the OBS video source and awards every active chatter a flat coin bonus calculated by the train's final level.

Tiered Slot Machine (Channel Points)

Listens for specific channel point redemptions named exactly "Play 10", "Play 20", or "Play 50". Features dynamic emoji reels (🍒, 🍋, 💎, etc.) and tiered payouts (Small, Medium, Big) based on the bet amount:

  • Play 10: 35% chance (x2), 20% chance (x3), 10% chance (x5).
  • Play 20: 25% chance (x2), 15% chance (x4), 10% chance (x10).
  • Play 50 (High Roller): 15% chance (x2), 10% chance (x5), 5% base chance (x20). Includes a Progressive Jackpot mechanic stored in the database where every loss increases the Big Win odds by 1% until hit!

4. Commands

!testmode Broadcaster

Toggles offline checks on and off. When enabled, the bot will not automatically shut down if the stream goes offline, allowing for safe testing.

!testhype Broadcaster

Triggers the OBS WebSocket connection to display the Hype Train video for exactly 10 seconds before hiding it again. Used for testing the live stream view.

!testraid Broadcaster

Simulates the visual and audio OBS triggers for an incoming raid for testing purposes.

!banuser @username Broadcaster

Flags a user in the database so they no longer passively earn XP during the payout intervals, and wipes their current XP and coins to zero.

!wipebanned Broadcaster

A bulk maintenance command that resets the XP and coins to zero for every single user currently flagged as banned in the database.

!unbanuser @username Broadcaster

Removes the XP ban flag from a user.

!deleteuser @username Broadcaster

Completely purges a user's record (XP, Level, Coins) from the SQLite database.

!addcoins <amount> @username Broadcaster

Instantly deposits a specific amount of virtual coins into a user's account.

!removecoins <amount> @username Broadcaster

Deducts a specific amount of virtual coins from a user's account.

!so @username Broadcaster

Gives a shout out to a specified user, automatically fetching their last played game and linking their channel in chat.

!resetjackpot Broadcaster

Manually resets the High Roller progressive jackpot odds back to the default 5% and updates the database.

!jackpot Broadcaster

Checks and displays the current win percentage for the High Roller jackpot in chat.

!level Everyone 60s Cooldown (User)

Displays the user's current level and total accumulated XP.

!coins Everyone 10s Cooldown (User)

Displays the user's current virtual coin balance.

!rank Everyone 300s Cooldown (Global)

Displays the top leaderboard of viewers based on highest Level and XP.

!quote <text> Everyone 10s Cooldown (User)

Saves a custom quote to the vault (text file), automatically appending the current date, stream channel, and the username of the person who captured it.

!getquote Everyone 15s Cooldown (Global)

Retrieves and displays a random quote from the vault.

!shop Everyone 10s Cooldown (Global)

Provides a direct link to the interactive web shop where viewers can browse and copy commands for video and audio rewards.

!buy <ID> Everyone

Deducts coins from the user's balance and plays an item. If the item is an audio file, it plays via Pygame. If it is a video file, it toggles the designated source in OBS. Video redemptions share a strict 60-second global cooldown to prevent visual spam. Note: The Broadcaster and specific super-users bypass all coin costs and cooldowns.

!timer Everyone 15s Cooldown (Global)

Uses OBS WebSockets to trigger a specific hotkey sequence (Ctrl + Alt + T), interacting with the on-screen stream timer script.

5. File Structure & Dependencies