asanrom/showdown-chatbot repository overview

⁠Showdown ChatBot

Pokemon Showdown⁠ bot written for Node JS⁠ with a ton of features often useful for chat rooms like automated moderation, blacklist, customizable help / information commands, games, tournament tools and chat logs. All of those features can be configured with a web control panel that does not require any programming knowledge to be used.

⁠Features

• Control Panel: You can configure your bot using a web control panel. You do not need to edit any file manually.
• Modular design: You can create and install add-ons in order to add new features (for example new commands or new options for the control panel). You can also enable and disable modules depending of your requires.
• Multi-Language: Bot commands and modules can operate in multiple languages at the same time (for example for language rooms). Currently only English and Spanish are implemented. However, you can create new languages and translate the language files via your bot's control panel.
• Dynamic commands: You can create custom text commands (the bot replies with a plain text) and html commands (the bot replies with an /htmlbox if it has permission). You can do this using commands or using the control panel.
• Logs: You can log chat rooms and bot's private messages. You also have a security log for important events and crash reports.
• Backups: You can save backups and restore them later (only configuration files, not logs or seen data). You can find this option in your bot's control panel, Tools option, Backups sub-option.
• Automated Moderation: Filters like capitals, stretching, spoiler or banned words, with automated detection and punishment.
• Blacklist: Permanent banning for chat rooms.
• Automated Battle Bot: This bot can play Pokemon battles itself. It is not an artificial intelligence, but the algorithm is good enough to be a threat for less skilled players, specially in formats with random generated teams. It can participate in scripted tournaments, ladder and accept battles from users. You can give it teams via the control panel and configure it in the Battle Bot option.
• Tournaments Tools: Tournament command (to create, start and set the auto-dq in a single command) and tournament leaderboards, with automated top 100 tables generation and customizable points system.
• Chat Games: Hangman, anagrams, mini-blackjack, pass the bomb, trivia and kunc.
• Pokemon Commands: Useful Pokemon related commands not implemented in Pokemon Showdown, like Smogon usage stats and translation commands.
• Auto-Invite: Automated /invite message sent to the staff (for private rooms).
• Players-Auction: You can create and play players auctions using commands (for team tournaments).
• Finding Users Tools: Automatically saves the last time an user did something in a room where the bot was (this data is stored in hard disk, so it is permanent). Also tracks alts from name changes. Users can use seen and alts commands to easily find other users.
• Groupchat Tools: Automatically maintains groupchats (temporal rooms) and promotes users.
• Others: Quotes and jokes, join-phrases, commands like helix, etc.

⁠Installation

First, make sure to install Docker⁠ and Docker compose⁠ in your system. You can also install other runtime, like Podman⁠, but the commands may vary.

Create a file named docker-compose.yml, and copy the following content into it:

version: "3.9"

services:
  bot:
    image: asanrom/showdown-chatbot
    ports:
      - "8080:8080"
      - "443:443"
    volumes:
      - ./config:/bot/config
      - ./data:/bot/data
      - ./logs:/bot/logs
      - ./instances:/bot/instances
    environment:
      - DEFAULT_ADMIN_USERNAME=Admin
      - DEFAULT_ADMIN_PASSWORD=admin
    restart: unless-stopped
    command: -p 8080 -b 0.0.0.0

If you want to use a different port for the control panel, make sure to replace 8080 with the port you want.

Here is a list of options you can include in the command section:

• -p [port] - Changes the HTTP listening port of the control panel. Default: 8080
• -b [address] - Changes the listening address of the control panel.
• -d [path] - Sets the path to store the configuration and data (default: /bot)
• -i [instance] - Uses a named instance as configuration (will be saved in the instances) folder. If this option is set, -d is ignored.
• -sp [port] - Changes the HTTPS listening port of the control panel. Default: 443
• -k [ssl-key] - Changes the path to the SSL key for HTTPS.
• -c [ssl-cert] - Changes the path to the SSL certificate for HTTPS.
• --static - Runs bot in static mode. In this mode, addons and eval commands are permanently disabled.

Here is a list of environment variables you can include in the environment section:

• DEFAULT_ADMIN_USERNAME - If the panel has no users, an admin user will be created with this username.
• DEFAULT_ADMIN_PASSWORD - If the panel has no users, an admin user will be created with this password.

Once you have the docker-compose.yml, in order to start the bot, open a terminal / command prompt in the folder where the file is located, and type the following command:

docker compose up -d

Configure your bot using the control panel. You can use the Basic Configuration Guide⁠ as help.

If you want to keep the image updated to the latest version automatically, you can use a tool like Watchtower⁠. You can also pull the image and restart the containers manually:

# Update the image and restart the containers
docker compose pull
docker compose up -d

⁠Useful Documentation

• Frequently Asked Questions⁠
• Commands List⁠

For more guides and documentation, check the Showdown-ChatBot Wiki⁠

⁠Add-ons

Add-ons are like optional modules you can install for your bot. They are rather limited and have no translation feature but they can be used to add custom commands and very specific features to your bot. Some public add-ons here⁠.

⁠Contributing

• Contributing guidelines⁠