- Added readme.md
parent
93e74f24df
commit
2a977fe76e
|
|
@ -0,0 +1,152 @@
|
||||||
|
# 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
|
||||||
Loading…
Reference in New Issue