CSBot

(Proper name TBD)

This project is undergoing rapid development and should be considered experimental. Use it at your own risk. 🤙

A bot to help manage the activities and community of BYU's Computer Science Discord server.

This project is meant as a successor to Ze-Kaiser, whose original contributors are as follows, in alphabetical order:

Authors & Contributors

These users contributed various things over time directly to this codebase. This list is ordered roughly by when users first contributed code. We add to this list as people contribute.

Contributing

This project is entirely open-source. Do with it what you will. If you're willing to help us improve this project, consider filing an issue.

See CONTRIBUTING.md for ways to contribute.

License

This project's source is licensed under the Unlicense license. All contributions to this project's source are understood to be given to the public domain.

CSBot

Chat Input Commands

You can find these in Discord by typing / in the message input box in any channel where you're allowed to run commands.

/help

Prints some info about the bot, including the current running version and a link to the code repository.

/profile

Retrieves the profile picture of the given user.

/xkcd

Retrieves the most recent xkcd comic, or the given one.

/talk

Uses the dectalk text-to-speech engine to speak the message you give it, either sending a .wav file in a text channel or talking out loud in a voice channel. Comes with 9 different voices.

/update

Pulls the latest changes from the repository and restarts the bot.

/tothegallows

Begins a new game of Evil Hangman.

/findroom ( now / at / between / when )

Searches for open rooms on BYU Campus. 'Now', 'At', and 'Between' allow you to filter your search by time. 'When' allows you to see when a specified room is available.

Context Menu Commands

You can find these in Discord by invoking the context menu (right-clicking) on any message in any channel where you're allowed to run commands.

Fix Twitter Links

Transforms twitter.com links in the given message to FixTweet links in an ephemeral reply. Please use fxtwitter in your own messages, especially when the tweet is a video. Twitter's default embed stinks on some platforms.

Talk

Performs the same function as the /talk chat input command, but uses the selected message as input. Can be used to repeat the same 'talk' command without typing it out again.

Usage or Development

If you've read this far, and don't plan to run or develop on the bot yourself, or are not curious how to do so, you may leave now. This part is quite boring. But feel free to read on anyway!

Prerequisites

This project requires NodeJS (version 16.19 or later) and NPM. To make sure you have them available on your machine, try running the following command:

$ node -v && npm -v
v16.19.0
8.19.3

If you are using Linux, you will also need to install the following package to use the /talk command:

$ apt install libpulse0

If you don't want to install Node or any other dependencies on your machine, you may also use Docker. Docker runs the project in a lightweight virtual Linux environment will all dependencies pre-installed, so functionality will be identical on any operating system.

All Docker management (like building, running, and cleaning up images and containers) has been automated, so you only have to follow a few simple steps.

You can install Docker from their website linked above. To make sure Docker is available on your machine, run the following command:

$ docker -v
Docker version 20.10.22, build 3a2c30b

Clone the Repo

$ cd path/to/parent
$ git clone https://github.com/BYU-CS-Discord/CSBot.git
$ cd CSBot

Get your own bot token

Note that, by running this bot, you agree to be bound by the Discord's Developer Terms of Service and Developer Policy, as well as this project's own license. With that in mind, you'll need a token for a Discord bot account. See this awesome tutorial on how to get one.

Configure the bot

Create a file called .env in the root of this project folder. Paste your token into that file, and fill in other config items as desired:

# .env

DISCORD_TOKEN=YOUR_TOKEN_GOES_HERE
# required, token for your Discord bot

DATABASE_URL=YOUR_DATABASE_URL_GOES_HERE
# required for any DB functionality, we will get this URL in a later section

ADMINISTRATORS=COMMA,SEPARATED,ID,LIST
# Required for the update command. WARNING: The users whose ids are listed here will be able to pull, build, and run code from this repository on the machine the bot is running on. Do not include any users you do not trust.

Do not commit this file to git or your bot will get "hacked".

Invite your bot to your server

Go to https://discordapi.com/permissions.html#378091424832 and paste in your bot's client ID to get an invite link.

Setting up Docker

Highly Recommended!

If you are using Visual Studio Code, you can use the Dev Containers extension, which will run the whole project in the Docker container. If you choose to do so, you can ignore every Docker instruction after this. Very nifty!

If you wish to run the project in Docker, use the following command before continuing:

$ npm run docker

This will build a simple Linux image, start a container of that image, and then mount the project folder into the container.

Once the container is started, you will see your command prompt change. You are now in a virtual Linux environment. If you run ls, you will see all the project files. Any changes you make to these files are synced between your local computer and the container.

Now that your command line is in the Docker container, you can run any part of the project and develop without worrying about compatibility.

To close the container, simply run exit. To start a new container, use npm run docker again. Every time you open the project, you should start a container before developing.

The docker script will take care of every part of the docker development process, including building, running, and cleaning up, so you only need to worry about a single command.

Build the bot

Be sure to install dependencies, run a quick lint to generate needed files, compile the source, and deploy commands. Here's a handy command to do all of that:

$ npm run setup

Build the bot database

As we use Prisma for managing our database, it is up to you what relational database framework to use.

Here is a guide to setting up Postgres inside a Docker container (note: this will be a separate Docker container from the one used for running the bot itself).

While the choice of database is up to you, the instructions for getting started in this guide assume you are using the Postgres Docker image.

After you have Postgres (or your database of choice) up and running, edit this line in your .env file:

DATABASE_URL=postgres://{pg_user}:{pg_pass}@{pg_hostname}:{pg_port}/{pg_db}
# required for any database functionality, we will get this URL in a later section

pg_user = The Username you set in your POSTGRES_USER environment variable (default postgres)
pg_pass = The Password you set in your POSTGRES_PASS environment variable (default postgres)
ph_host = The IP of the server running your Postgres instance (default localhost)
pg_port = The Port assigned to your Postgres instance (default 5432)
pg_db = The Name of the database you wish to use for the bot

The first time you run this project, you should run the following command to initialize the database:

$ npm run db:init

Migrations can be run on the database with the following command:

$ npm run db:migrate

Register Slash Commands

If you want support for Discord Slash Commands, you'll need to deploy the commands directly. To avoid rate limits, use a command-line tool, rather than deploying on startup.

Once you have your bot's account token in the .env file, run the following command to tell Discord about our commands:

$ npm run commands:deploy

Test the bot

Whenever you make changes, you should make sure to run all unit tests before submitting.

$ npm run test

If you have added new code, you should write new unit tests to cover all the code you've written. Our goal is 100% code coverage.

Run the bot

For development purposes (the update command will not work properly, but logs are outputed to the console):

$ node .
# or
$ npm run dev

For production purposes (this will spawn a separate thread using PM2 that will run in the background):

$ npm start
$ npm run stop
$ npm run restart

josephgeis / CSBot