Legacy - shinyfinder/chatot-smogon GitHub Wiki

STOP: If you are contributing to the current codebase, ignore this page!!! Please refer to the Installation and Runtime pages instead.

This page serves as a resource for the chatot-smogon directory (the parent directory for this wiki). While this public code is no longer maintained, I realize that some may want to practice playing around with Chatot before contributing to the real thing. The steps here will give you more specific information when interacting with this repo's code. However, when go to contribute to the updated codebase, please refer to the rest of this wiki.

Dependencies and the Discord API have updated since this code was used. It's possible that it no longer works as is.

Note that the bot is hosted on a Linux system. While the code and be run on any OS, ultimately that is the one used in production on the Smogon servers. While beyond the scope of this wiki, you may find it prudent to use Docker or, for Windows users, installation of WSL. Windows users are recommended to use WSL if they plan on contributing to development.

Whether you are planning on running a local copy or contributing to development, the first thing you'll need to do is install Node. This code assumes you have v.16.9.0 or later installed of NodeJs. Please install or update that first before proceeding. The package manager of choice for this project is pnpm. It can be installed with npm (installed by default with node) with the following, or any of the other methods on their website.

npm install -g pnpm

Once you have installed Node and pnpm, you'll want to obtain a copy of the code from this repo. Obtain a copy of the source code by downloading the zip of the repository or, if you have git installed, via the command line in your desired destination folder:

git clone https://github.com/shinyfinder/chatot-smogon.git

If you download the zip, extract the file into your desired directory.

Installing the packages required by the bot is easy. Within the command line, in the same directory as the package.json file, run

pnpm install

The program will automatically install all of the required packages.

Make a copy of the provided file .sample-env and rename the copy to .env. Thie file contains the environment variables required for the bot to run. Never give out the values in this file! Please refer to the discord.js documentation for setting up your bot application and adding the bot to your server(s) to obtain these values.

For full functionality, the bot needs access to all 3 privileged intents (guild pressences, guild members, and message content).

Additions to the environment variables will need to be reflected in config.ts. These values are accessed within the bot as botConfig.VARIABLE_NAME.

Many of the functions of the bot rely on access to a PostgreSQL (PG/Postgres) database, and when interacting with the Smogon forums, a MySQL database. Postgres is an open source database system that extends the usage of SQL. If you aren't sure what that means, don't worry about it. If you're familiar with JS, you've likely come across JSON files, which are files commonly used to store data locally. Postgres is an alternative storage method in which data is stored in tables. Think of it like a big spreadsheet. The tables in this database are how the bot stores data between command executions and startups. As you work with it, you'll quickly find it a superior method to managing large datasets and filtering data.

Installation and usage of Postgres and MySQL is beyond the scope of this guide. However, you can find guides to these tasks across the internet, such as this one to download and the official manual. The easiest method is to create a PG and MySQL server on the localhost on the default port. It will run in the background alongside the bot.

Once you have PG installed, create a database for the bot. The defaults are a username of postgres, hosted localhost on port 5432. Whatever values you choose, enter this information into your .env.

The schema (database definitions) are defined in the /src/sql/schema.sql file. Once you have the PG server up and running, use the psql command line tool to create the schema and tables necessary for the bot. You can copy and paste the values in this file.

You can see that you have a table setup corretly by trying to query it within the psql command line. For example,

SELECT * FROM chatot.servers;

Will show you all of the rows and columns in that table (there will not be any rows because we haven't stored anything yet).

Follow a similar procedure for setting up a MySQL connection. The schema used by the forums can be found here; however, you do not need the entire schema. The exact tables and columns you need are best inferred from Chatot's source code.

Both databases are required to fully run Chatot. If you wish to contribute to development with simple changes and do not want to go through the process of setting up a database connection, you may set the SKIP_DB flag to true within your .env. This will short-circuit the startup procedure and skip the connections to the databases; as a result, many of Chatot's commands will not work, but you will be able to start the bot. This is not the best way to run Chatot, but it will work in a pinch and may be helpful if your contributions do not rely on a database.

By this point it is assumed you have already made a development server and bot application within the Discord developer portal, as linked above. If you are just trying to run a local copy, you can proceed to the Utilizing the Bot section. If you plan on contributing to development, read on.

It is strongly recommended (read: required) to use Git and a robust IDE such as VS Code when contributing to development. This section will assume you are using both. Proper usage of these tools is beyond the scope of this wiki, but some common commands in git you will need are

git pull
git add .
git commit -m 'commit message goes here'
git push origin main
git stash
git stash pop

For Windows users using WSL, Microsoft has a tutorial for setting up a WSL development environment. They have put a lot of effort into making the integration of Windows, Linux, and VS Code seamless, so following their guide is the best advice. Docker and GPU acceleration are not required, but you can look into that if you wish.

The only VS Code extension not covered in the above guide is ESLint. To ensure your additions to the code are consistent with the existing rules, it is recommended to install the ESLint extension if you are contributing to development. Linters analyze your code for format errors and best practices. While not required, it is nice to have and ensures a consistent experience no matter who contributes to development. Remember that linters are a guide and can be too strict for your needs. Sometimes you need to overrule them.

This bot uses slash commands (a subset of application commands). Deployment of these commands is handled during startup of the bot witihn the /src/helpers/updateState.ts file. This script detects any changes in your command definitions and (re)deploys them as appropriate. The deployment scope is defined within the command definitions themselves with the following flags:

global: <boolean>
guilds: <string[]>

Setting the global flag to true will cause the command to be deployed globally (i.e. to every server the bot is in). Setting the global flag to false and providing a list of server IDs as strings within the guilds array will instead deploy the command as a guild command (i.e. only to that guild) to the listed servers. Note that if the bot is in dev mode (its client id is equal to a value specifed in /src/helpers/hashCommands.ts), the specified guild array will be overwritten with the dev guild id specifed in the .env.

Start the bot from the terminal with the following:

pnpm build
pnpm start

You should see that the bot is now online in Discord. To confirm it is responding to commands, post the following within Discord:

/ping

The bot should respond with "Pong!".

Comments are provided within the *.ts files to offer a more precise understanding of what the code is doing line-by-line. For the sake of providiing a general overview, the core components of the bot are separated into different directories within /src. Any additions you make to the code will likely go within this folder. Commands (user interfaces with the bot) and events (triggers the bot listens for) are separated into their respective directories. Further, each command and event is given its own file. While it may be possible to oranize the files into further subdirectories, each feature being given its own file allows for easier debugging and isolation of code. Any functions used by the commands or multiple files are stored in the /helpers directoy. Type defintions needed by multiple files are stored within the /types directory.