(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:
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.
- ZYancey (profile)
- gmacgre (profile)
- JstnMcBrd (profile)
- AverageHelper (profile)
- SpencerHastings (profile)
- Plyb (profile)
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.
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.
You can find these in Discord by typing /
in the message input box in any channel where you're allowed to run commands.
Prints some info about the bot, including the current running version and a link to the code repository.
Retrieves the profile picture of the given user.
Retrieves the most recent xkcd comic, or the given one.
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.
Pulls the latest changes from the repository and restarts the bot.
Begins a new game of Evil Hangman.
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.
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.
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.
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.
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!
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
$ cd path/to/parent
$ git clone https://github.com/BYU-CS-Discord/CSBot.git
$ cd CSBot
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.
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".
Go to https://discordapi.com/permissions.html#378091424832 and paste in your bot's client ID to get an invite link.
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.
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
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
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
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.
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