153 lines
5.9 KiB
Markdown
153 lines
5.9 KiB
Markdown
# OokamiPup V2
|
||
|
||
## A combined Discord and Twitch bot written in Python, leveraging:
|
||
|
||
- discord.py (PyPI version discord.py or a maintained fork)
|
||
- TwitchIO
|
||
- aiohttp
|
||
- python-dotenv
|
||
- and other libraries listed in your requirements.txt.
|
||
|
||
## About the bot
|
||
|
||
- Monitors specified Twitch channels for messages and commands.
|
||
- Connects to a specified Discord server to respond to commands and events.
|
||
- Uses a .env file for storing sensitive credentials.
|
||
- Uses a config.json for channel configuration, logging settings, etc.
|
||
|
||
## Features
|
||
|
||
- Discord Bot
|
||
- Responds to commands from any channel or restricted channels (depending on your setup).
|
||
- Automatically loads commands from cmd_discord.py.
|
||
- Twitch Bot
|
||
- Joins multiple Twitch channels specified in your config.json.
|
||
- Automatically loads commands from cmd_twitch.py.
|
||
- Simple Logging
|
||
- Logs to the console with optional levels (DEBUG, INFO, WARNING, etc.).
|
||
- Token Refresh
|
||
- Automatically attempts to refresh your Twitch OAuth token if it becomes invalid.
|
||
|
||
## Prerequisites
|
||
|
||
- Python 3.8+ (or a compatible Python 3 version—ensure asyncio.run is supported).
|
||
- A Twitch Developer application (for your Client ID and Client Secret).
|
||
- A Discord application/bot token.
|
||
- A working pip or pipenv/poetry for installing dependencies.
|
||
|
||
## Installation
|
||
|
||
Clone this repository (or download the source code):
|
||
|
||
1. `git clone https://git.ookamikun.tv/kami/OokamiPupV2.git` *(Clone repository)*
|
||
2. `cd OokamiPupV2` *(Navigate into the project folder)*
|
||
3. `pip install -r requirements.txt` *(Install project dependancies)*
|
||
|
||
Create your .env file in the project root (same folder as `bots.py`). It should look like:
|
||
|
||
```python
|
||
DISCORD_BOT_TOKEN=YourDiscordBotToken
|
||
TWITCH_CLIENT_ID=YourTwitchAppClientID
|
||
TWITCH_CLIENT_SECRET=YourTwitchAppClientSecret
|
||
TWITCH_BOT_TOKEN=YourTwitchOAuthToken
|
||
TWITCH_REFRESH_TOKEN=YourTwitchRefreshToken
|
||
```
|
||
|
||
Note: Your Twitch OAuth/Refresh tokens typically come from generating them through the Twitch Developer Console.
|
||
|
||
Set up your config.json with your preferred channels, logging levels, etc. For example:
|
||
|
||
```json
|
||
{
|
||
"twitch_channels": ["mychannel", "anotherchannel"],
|
||
"log_levels": ["INFO", "WARNING", "ERROR", "CRITICAL", "FATAL"]
|
||
}
|
||
```
|
||
|
||
twitch_channels is a list of channel names for your bot to join on Twitch.
|
||
log_levels controls what messages get logged to console (The lowest "DEBUG" level can be added if needed).
|
||
|
||
## Directory Overview
|
||
|
||
A quick rundown of the important files:
|
||
|
||
```bash
|
||
.
|
||
├── bots.py # Main entry point: initializes/starts both Discord and Twitch bots
|
||
├── bot_discord.py # Discord bot implementation (using discord.py)
|
||
├── bot_twitch.py # Twitch bot implementation (using TwitchIO)
|
||
├── cmd_common/ # Platform-independant command logic
|
||
│ └── common_commands.py # Common low-level commands file
|
||
├── cmd_discord.py # Command definitions for Discord
|
||
├── cmd_twitch.py # Command definitions for Twitch
|
||
├── config.json # Bot configuration (channels, logging levels, etc.)
|
||
├── .env # Environment variables for tokens (DO NOT commit this)
|
||
├── requirements.txt # Python dependencies
|
||
└── README.md # You are here
|
||
```
|
||
|
||
## Usage
|
||
|
||
1. Edit your environment variables in the .env file (tokens, client IDs, secrets, etc.).
|
||
2. Edit your config.json to list the Twitch channels and your logging preferences.
|
||
3. Run the bot: `python bots.py`
|
||
4. Check the console output:
|
||
- You should see logs indicating that the Discord bot is online (Discord bot is online as ...).
|
||
- You should also see logs about the Twitch bot joining channels (Twitch bot connected) — assuming everything is configured correctly.
|
||
|
||
## Testing Commands
|
||
|
||
**Discord:**
|
||
|
||
Open your Discord server, type your command prefix (e.g., !) + the command name (e.g., !ping).
|
||
|
||
**Twitch:**
|
||
|
||
In one of the channels specified in twitch_channels, type !ping (or whichever commands you have set up in cmd_twitch.py).
|
||
|
||
### If your commands do not respond
|
||
|
||
- Confirm the bot has correct roles/permissions in Discord (especially if it needs to read/send messages in specific channels).
|
||
- Confirm your Twitch OAuth token is valid.
|
||
- Check for logs or errors in the console.
|
||
|
||
## Adding or Editing Commands
|
||
|
||
**General Commands:**
|
||
|
||
low-level commands can be made in `cmd_common/common_commands.py`, alternatively separated into separate files in that folder.
|
||
|
||
These are command logic meant to support both platforms, eg. the `!ping` command.
|
||
|
||
**Discord:**
|
||
|
||
- Open cmd_discord.py and define new commands using the standard @bot.command() decorators from discord.ext.commands.
|
||
- Make sure cmd_discord.setup(bot) registers them with your DiscordBot.
|
||
|
||
**Twitch:**
|
||
|
||
- Open cmd_twitch.py and define new commands using the @bot.command() decorators from twitchio.ext.commands.
|
||
- Ensure cmd_twitch.setup(bot) properly registers them with TwitchBot.
|
||
|
||
## Troubleshooting
|
||
|
||
- No logs from the Twitch bot
|
||
- Ensure that you’re calling await bot.start() (not bot.run() and await bot.start() together).
|
||
- If you only see the Discord bot logs, verify that your .env variables are loaded and valid (TWITCH_CLIENT_ID, TWITCH_CLIENT_SECRET, TWITCH_BOT_TOKEN, TWITCH_REFRESH_TOKEN).
|
||
- Confirm that you have internet connectivity and that the Twitch IRC service isn’t blocked by a firewall.
|
||
|
||
- Token refresh issues
|
||
- If you see repeated warnings about “Invalid or unauthorized Access Token,” double-check your TWITCH_REFRESH_TOKEN and TWITCH_CLIENT_SECRET are correct.
|
||
- The bot attempts to refresh automatically; if it still fails, manually re-generate tokens from the Twitch Developer Console.
|
||
|
||
- "Cannot write to closing transport"
|
||
- Make sure you do not call connect() manually before start() in TwitchIO.
|
||
|
||
## Contributing
|
||
|
||
- Fork the repository
|
||
- Create a new branch (git checkout -b feature/myfeature)
|
||
- Make changes and commit (git commit -am 'Add new feature')
|
||
- Push to the branch (git push origin feature/myfeature)
|
||
- Create a new Pull Request in Git
|