diff --git a/readme.md b/readme.md new file mode 100644 index 0000000..66eb7bb --- /dev/null +++ b/readme.md @@ -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