Contributing - shinyfinder/chatot-smogon GitHub Wiki

Note

The source code for Chatot has been moved to the main Smogon repo and does not pull from this repository anymore. However, this wiki is still updated to reflect the current codebase. Legacy instructions for working with the code in this repo can be found on the Legacy page.

If you're looking to add Chatot to your servers, refer to the Quickstart guide or the more in-depth User Guide instead.

Software

  • Docker
  • v.24.x LTS or later installed of NodeJs
  • pnpm 11.x - npm install -g pnpm
  • Git
  • Recommended: WSL (Windows users)
  • Recommended: VS Code
  • Recommended: oxlint (VS Code extension)

Once you have installed these dependencies, you'll want to obtain a copy of the code. Please confer with chaos for access.

Installation

  1. Obtain a copy of the source code with git clone https://github.com/smogon/smogon.com.git
  2. Open a terminal and navigate to installation_directory/smogon.com. Install the dependencies via pnpm install.
  3. If you haven't already, create a file called .env inside the ./smogon.com directory. The keys needed in this file can be found in the README(https://github.com/smogon/smogon.com/tree/master/chatot). This 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 the values for your application.

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

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

  1. Ensure Docker is running on your machine. You don't need to have any containers running, it just needs to be open (resource saving mode is fine).

  2. In a terminal in the ./smogon.com/ directory, start the bot with pnpm chatot.

  3. You should see that the bot is now online in Discord. To confirm it is responding to commands, type /ping within Discord and send. The bot should respond with "Pong!".

Dev Loop

Once you have everything setup, your typical startup procedure will be:

<Ensure Docker is running>
pnpm chatot

Your running instance of Chatot can be turned off with Ctrl+C within the terminal that's running it. This will trigger the shutdown sequence.

Commentary

Using the bot

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. Each command type is instantiated as a class defined within /src/helpers/commands.ts. The class you choose determines the scope of the command. Generally speaking, global commands are available in all guilds the bot is in, and guild commands are only available in the list of specified guild IDs.

Note that if the bot is in dev mode (as specified in your .env; it should always be in this mode!), the specified guild array will be overwritten with the dev guild id specifed in the .env, which means you only need to be concerned with inputting the production values to the command definitions.

Database connections

Chatot primarily uses Postgres for its storage; the schema is defined in the schema.sql file. However, certain features (such as /verify and C&C/CA monitoring) require a mySQL connection, as that is the schema used by Xenforo. Please refer to the forum's source code for that schema; the specific tables used by Chatot can be found within the respective functions.

Chatot now runs in dev mode under testcontainers, eliminating the need for devs to install and manage their own SQL databases. This requires Docker to at least be installed (you do not need to create a Docker image, but you can if you want for your own purposes). This is done by setting SMOGON_TUNNEL=docker:chatot within your .env. The data written to these databases persist across bot restarts.

Dex information is seeded into the databases when they are first created, which should suffice for most needs; however, if you wish to query against production, set SMOGON_TUNNEL=smogon within your .env. Please confer with chaos for your options in obtaining this access.

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 the official Postgres manual.

Code organization

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.

While writing a command, you should always keep in mind any unit tests you can write for it (especially if the command requires a database call). There are plenty of examples throughout the code base (see: /src/tests). Tests can be run with pnpm test or pnpm db-test. If you only wish to run a specific test (i.e. you're actively writing code), you can run pnpm [test|db-test] [filename] -- i.e. pnpm test draft to execute draft.test.ts.

Further Reading

Please refer to the Discord documentation for further information on adding, using, and deleting slash commands. For more in-depth information, see the devloper documentation on application commands.

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, 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.

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 master
git stash
git stash pop