mcmodersd/yeppbot repository overview

⁠YEPPBot - YEPP it's a Twitch Bot⁠

⁠Description

YEPPBot is a comprehensive Twitch bot featuring numerous tools to entertain and manage your Twitch channel.

Originally conceived by FoxxHimself⁠ and written in Python in early 2021.
I took over the project after the original creator ceased development and rewrote it using Java 21 with the Twitch4J⁠ library.

⁠Usage

You can explore the bot's features live on its Twitch chat⁠.
To integrate it with your channel, use the command !mod join.
If you ever want to remove it, simply use !mod leave.

For optimal functionality, it's necessary to authenticate the bot with your Twitch account via !mod auth.
While not mandatory, assigning the bot a moderator role is advised for all features to work as intended.

⁠Contact and Support

For support or inquiries, reach out via Discord⁠, mail⁠, or Twitch⁠.
I typically respond within 24 hours, oftentimes sooner.

Interested in collaboration or a custom version tailored to your needs? Simply email [email protected]⁠.

Note that the bot is under active development, and some features may change considerably in the future.
Consequently, the setup process may also evolve.

⁠Host Your Own Instance

You can use this project as a template to create your own bot or to host an instance.
You have three options to host and run the bot:

• Docker⁠
• Precompiled JAR⁠
• Manual Setup⁠

Regardless of your chosen method, you'll need to prepare configuration files according to the Configuration⁠ section instructions.
You can generate example configuration files using the -generate argument.

⁠Docker

You can run the bot within a Docker container.
The Docker image is available on Docker Hub⁠.
Make sure to mount your configuration files to the container at /app/config.

⁠Precompiled JAR

Ensure that Java 21 is installed on your system, which is available here⁠.
Download the latest version from the releases⁠ page.
Run the precompiled JAR, providing absolute paths to the required configuration files:

java -jar YEPPBot.jar -bot "/path/to/bot.json" -sql "/path/to/sql.json" -server "/path/to/server.json" ...

Arguments for configuration files include:

• -bot "/path/to/bot.json": Specifies the bot configuration file path. (required)
• -channels "/path/to/channels.txt": Specifies the channel list file path. (optional)
• -sql "/path/to/sql.json": Specifies the MariaDB configuration file path. (required)
• -server "/path/to/server.json": Specifies the HTTPS server configuration file path. (required)
• -api "/path/to/api.json": Specifies the API keys configuration file path. (optional)
• -openai "/path/to/openai.json": Specifies the ChatGPT configuration file path. (optional)

Other available arguments:

• -help: Lists all available arguments.
• -version: Displays the current version of the bot.
• -cli: Runs the bot in command-line mode.
• -nolog: Disables database logging.
• -noninteractive: Disables interactive mode.
• -container: Enables Docker container mode.
• -generate: Produces example configuration files.

⁠Manual Setup

To manually compile and run the bot, first, install Java 21 as detailed here⁠.
Clone the project into your IDE and organize the configuration files:

• bot.json, channels.txt, and server.json should be in /src/main/resources/config/.
• sql.json should be in /src/main/resources/database/.
• api.json and openai.json should be in /src/main/resources/api/.

Build and run the project following setup.

⁠Configuration

Before setting up:

1. Create a Twitch app through the Twitch Developer Console⁠.
2. Establish a Twitch account for the bot (using your own is viable but not ideal).
3. Set up a MariaDB database and user for the bot.

Account tokens may become invalid over time or if the password changes.
Remember never share or post the token.

⁠Bot Configuration

Create bot.json with this format:

{
  "botId": "YOUR_BOT_ID",
  "botName": "YOUR_BOT_NAME, YOUR_BOT_ALIAS, YOUR_BOT_ALIAS",
  "botToken": "YOUR_BOT_TOKEN",
  "clientId": "YOUR_CLIENT_ID",
  "clientSecret": "YOUR_CLIENT_SECRET",
  "prefix": "! ¡",
  "admins": "ADMIN_NAME; OTHER_ADMIN_NAME"
}

• botId: Retrieve the Twitch user ID for the bot account using this converter⁠.
• botName: The bot's account name, allowing multiple recognitions separated by commas.
• botToken: Generate your bot account's token here⁠.
• clientId and clientSecret: Details from your Twitch app.
  • Create the application in the Twitch Developer Console⁠.
  • Set https://localhost:PORT/callback for OAuth redirect or your server's domain.
  • Opt for Chatbot category and Confidential for the client type.
• prefix: Symbols used to trigger commands.
• admins: Users allowed admin command execution. Admins can use all commands across channels.

⁠Channel List (optional)

Create channels.txt in this format:

CHANNEL_NAME
OTHER_CHANNEL_NAME

List as many channels as needed.
Without this list, the bot will function only in its own channel.

⁠MariaDB Database

You must set up a MariaDB database for data management.
The bot auto-generates necessary tables.

Set up MariaDB using:

CREATE DATABASE DATABASE_NAME;
CREATE USER 'USER_NAME'@'%' IDENTIFIED BY 'USER_PASSWORD';
GRANT ALL PRIVILEGES ON DATABASE_NAME.* TO 'USER_NAME'@'%';
FLUSH PRIVILEGES;

If the bot and database share a server, replace % with localhost.

Create sql.json like:

{
  "host": "localhost",
  "port": "3306",
  "database": "DATABASE_NAME",
  "username": "USER_NAME",
  "password": "USER_PASSWORD"
}

• host: Hostname/IP where MariaDB is hosted, e.g., localhost.
• port: Default MariaDB listening port (3306).
• database: The bot's database name.
• username: The MariaDB user with database access.
• password: Password for the MariaDB user.

Ensure the user has full permissions on the database.
Use -nolog to disable logging in the database.

⁠HTTPS Server

The bot includes an integrated HTTPS server for Twitch Helix API authentication and forthcoming features.
Set up server.json like:

{
  "hostname": "YOUR_HOSTNAME",
  "port": 443,
  "host": true,
  "proxy": "YOUR_PROXY",

  "SSL": {
    "fullchain": "/path/to/fullchain.pem",
    "privkey": "/path/to/privkey.pem"
  },

  "JKS": {
    "file": "keystore.jks",
    "password": "secure_password",
    "validity": 365,
    "CN": "Your Name",
    "OU": "Your Organization Unit",
    "O": "Your Organization",
    "L": "Your Location",
    "ST": "Your State",
    "C": "Your Country"
  }
}

⁠Fields Explained:

• hostname: Bind server to hostname/IP (e.g., localhost or public domain).
• port: Server port number (default: 443).
• SSL: For Docker users, mount certificate file directory.
  • fullchain: Path to SSL/TLS certificate chain file (.pem).
  • privkey: Path to corresponding private key file.
• JKS (Java KeyStore): Option to use JKS for SSL over .pem.
  • file: Path to Java KeyStore file.
  • password: Java KeyStore password.
  • validity: Days the certificate is valid.
  • CN: Common Name (this might be your domain name).
  • OU, O, L, ST, C: Certificate organizational and geographic details.

A valid certificate is required for domains. Self-signed certificates are for localhost only.
Obtain a free certificate from Let's Encrypt⁠.

⁠API Keys (optional)

Configure api.json for API keys:

{
  "astrology": {
    "clientId": "YOUR_ASTROLOGY_CLIENT_ID, OPTIONAL_SECOND_CLIENT_ID",
    "clientSecret": "YOUR_ASTROLOGY_CLIENT_SECRET, OPTIONAL_SECOND_CLIENT_SECRET"
  },

  "giphy": "YOUR_GIPHY_API_KEY",
  "openWeatherMap": "YOUR_OPEN_WEATHER_MAP_API_KEY",
  "riot": "YOUR_RIOT_API_KEY"
}

No need to include unused APIs.

⁠API Key Resources:

• Astrology API: Currently for horoscopes. Obtain from Prokerala⁠.
• OpenWeatherMap API: Powers weather-related commands. Obtain from OpenWeatherMap⁠.
• Giphy API: GIF searching functionality. Obtain from Giphy⁠.
• Riot API: For League of Legends data. Obtain from Riot Games⁠.

⁠OpenAI API (optional)

OpenAI API setup, required for some commands, is optional.
Configure openai.json as follows:

{
  "apiKey": "YOUR_API_KEY",
  "user": "YOUR_USERNAME",
  "organizationId": "YOUR_ORGANIZATION_ID",
  "projectId": "YOUR_PROJECT_ID",

  "chat": {
    "model": "gpt-4o-mini-2024-07-18",
    "temperature": 1,
    "topP": 1,
    "frequencyPenalty": 0,
    "presencePenalty": 0,
    "n": 1,
    "maxTokens": 120,
    "devMessage": "You are the best TwitchBot that ever existed!",
    "spendingLimit": 32768,
    "priceFactor": 0.25
  }
}

To retrieve your API key, visit OpenAI's Website⁠.
Fields regarding user, organization, and project IDs are non-mandatory and can be accessed on the OpenAI dashboard⁠.

⁠Chat Configuration

⁠Commands and Features

This bot includes various commands to enhance functionality and interaction.
Below is an overview of key commands:

⁠Help Commands

• !help commands: Displays a list of all available commands.
• !help COMMAND_NAME: Provides detailed information about a specific command.

⁠Moderation Commands

• !moderate join: Adds the bot to your channel.
• !moderate leave: Removes the bot from your channel.
• !moderate block COMMAND_NAME: Blocks a specific command from being used.
• !moderate unblock COMMAND_NAME: Unblocks a previously blocked command.

⁠Counter Commands

• !counter: Manages counters for various purposes.
• !counter add COUNTER_NAME: Adds a new counter.
• !counter remove COUNTER_NAME: Deletes an existing counter.
• !counter show COUNTER_NAME: Displays the current value of a counter.
• !counter set COUNTER_NAME VALUE: Sets the counter's value.
• !counter reset COUNTER_NAME: Resets the counter to its initial value.

⁠Custom Commands

Create and manage custom commands using !cc:

• !cc add COMMAND_NAME ALIAS: RESPONSE: Adds a new custom command.
• !cc remove COMMAND_NAME: Deletes a custom command.
• !cc enable COMMAND_NAME: Enables a disabled custom command.
• !cc disable COMMAND_NAME: Disables an enabled custom command.
• !cc list: Lists all custom commands.

Dynamic variables can be used within custom commands for interactivity:

• %author%: Replaced with the username of the command executor.
• %channel%: Replaced with the name of the channel.
• %tagged%: Replaced with the first word following the command. (useful for mentions)
• %random%: Replaced with a random percentage between 0 and 100.

⁠Info Commands

• !info moderator: Lists all moderators in the channel.
• !info editor: Lists all editors in the channel.
• !info vip: Lists all VIPs in the channel.

⁠Birthday Commands

• !birthday set DD.MM.CCYY: Sets your birthday.
• !birthday get USERNAME: Retrieves a user's birthday.
• !birthday next AMOUNT: Shows upcoming birthdays.
• !birthday in USERNAME TIME_FORMAT: Retrieves information on a user's birthday using a specific time format.
• !birthday list: Lists all birthdays.

⁠ChatGPT Commands

• !prompt MESSAGE: Generates a response from the prompt.
• !chat MESSAGE: Starts or continues a conversation with the bot.
• !chat reset: Resets the current conversation.

⁠Seasonal Event Commands

Similar commands apply for both the No Nut November and Dick Destroy December events:

• !NoNutNovember join: Joins the No Nut November event.
• !NoNutNovember leave: Leaves the No Nut November event.
• !NoNutNovember list: Lists participant statuses.
• !NoNutNovember status USERNAME: Checks a user's status.

⁠Quote Commands

• !quote QUOTE_ID: Retrieves a specific or random quote. (QUOTE_ID optional)
• !quote add QUOTE: Adds a new quote.
• !quote remove QUOTE_ID: Deletes a quote.
• !quote edit NEW_QUOTE QUOTE_ID: Edits an existing quote.
• !quote last: Retrieves the last quote added.

⁠Shoutout Commands

• !so USERNAME: Performs a shoutout for a specified user.
• !so enable: Enables automatic shoutouts for raids.
• !so disable: Disables automatic shoutouts for raids.

⁠General Commands

• !fact en/de: Provides a random fact in English or German. (language optional)
• !gif theme: Searches for a GIF based on the provided theme. (theme optional)
• !horoscope USERNAME LANGUAGE: Provides a user's daily horoscope. (language optional)
• !insult USERNAME: Insults the specified user.
• !joke en/de: Tells a random joke in English or German. (language optional)
• !lurk: Tracks and informs how long a user has been lurking.
• !match AMOUNT LANGUAGE: Shows compatible users based on zodiac sign. (amount & language optional)
• !ping: Checks the bot's latency.
• !riot USERNAME#TAG REGION: Provides info about a League of Legends player. (region optional)
• !say MESSAGE: Makes the bot say the specified message. (admin only)
• !status: Displays the bot's status.
• !translate LANGUAGE, TEXT: Translates text to the specified language.
• !weather LOCATION, LANGUAGE: Provides current weather information for a location. (language optional)
• !wiki en/de SEARCH_TERM: Searches Wikipedia for the term. (language optional)

⁠CLI Commands

• exit: Shuts down the bot.
• clear: Clears the console.
• help: Lists all available CLI commands.
• uptime: Displays the bot's uptime.
• generate: Generates example configuration files.

⁠Planned Features

• YEPPConnect: A Minecraft plug-in for whitelist management and Twitch integration.
• Key Command: Locating the least expensive game key.
• Custom Timer: Setting timed messages.
• Rank: Displays a user's rank in a game.
• Social: Shows a streamer's or user's social media.
• Web UI: A web interface for bot management.
• Discord Integration: Integration with Discord for cross-platform functionality.

⁠Contributing

Have ideas or feedback? Feel free to:

• Submit issues or requests on GitHub.
• Reach me on Discord⁠ or Twitch⁠.

⁠Acknowledgments

Special thanks to:

• FoxxHimself⁠: For initial bot creation and inspiration for the Java transition.
• RedSmileTV⁠: For API and library help.
• Rebix⁠: For guidance and support.
• Xander⁠: For assistance with Docker, CI/CD and pen-testing.
• r4kunnn⁠: For testing and feedback.

Your contributions and support are greatly appreciated.
Together, we can make the bot even better!