Introduction

A simple text-controlled Discord Bot written in Python. It can perform common math tasks, especially those geared towards randomness and simulation. You can join the test server to see the bot in action:

It is recommended to use the #math-bot-test channel to test the commands.

Usage

Example:

$mathbot mean 1 2 3 4 5

Refer to the documentation for all the supported commands and the syntax.

The source code for this bot is freely available under the MIT License. Anyone can clone this repository and host their own instance of this bot.

In case you find a bug, or notice that a certain feature is absent but want it to be added, consider looking at the existing issues. If nothing matches what you found, create a new Issue.

Instructions for Local Setup

This section contains instructions that can be followed by users to have their own instance of this bot running either on their local machine. These can be adapted fairly easily and users can host their bots online on services like Repl.it and Heroku.

Prerequisites

Install Git and Python

1. Install Python 3.8 or higher and make sure it is added to path.
2. Install Git, add it to path and configure the username and email.

A Github account is optional, but you will need it if you want to contribute code to this repository. Make sure you use the same email as in step 2.

Obtain the Source Code

1. Navigate to a directory where you want to store the project.
2. Type git clone https://github.com/hungrybluedev/math-bot.git
3. Enter the newly created directory using cd math-bot

Obtain Discord Token

Follow the relevant sections of this tutorial by FreeCodeCamp to obtain the required token.

⚠️ WARNING: Do not share this token with anyone else, especially online. Do not add it to a repository. If you have done so accidentally, you should regenerate the token immediately.

Install Dependencies

1. (Optional) If you want isolation, create a virtual environment using the virtialenv package. Install the dependencies when the environment is active.
2. In the root directory, run pip install -r requirements.txt

Prepare .env File

1. Create a new file with the name .env in the mathbot directory. This directory also contains files like main.py, commands.py, and so on.
2. Type DISCORD_TOKEN= and then paste the Discord Bot token generated in the previous step. Do not add spaces around the =.
3. Ensure that this file does not appear when you type git status in the terminal. If it does, add .env in a new line in the file .gitignore

Commands

Starting the Bot

Navigate to the root of the project and execute:

python -m mathbot.main

The bot will log in and block inputs. In order to exit the main loop, press Ctrl+C

Running the Unit Tests

In the root directory, execute:

python -m unittest mathbot.test

This will execute all the tests present in mathbot.test.py

Hosting an Instance

Generally, users might prefer hosting an instance of this bot (for free) rather than self-hosting it on their machines. Two approaches are recommended:

1. Using Repl.it - Users can follow this excellent tutorial by FreeCodeCamp to learn how to host an instance of this bot for free.
2. Using Heroku - Another approach that might need a bit more configuration than the previous one: following this tutorial by Tech with Tim.

However, the instances may not stay active despite the tricks mentioned. In this case, it is better to host it on a VPS.

1. Rent a VPS from a hosting provider.
2. Harden the server, add users, set up SSH, install updates, etc.
3. Connect via SSH.
4. Follow the instructions in the previous sections until the part where you start the bot.
5. Use nohup python3 -m mathbot.main & to create a detached process where the Bot will run independent of the SSH. Note the PID stated.
6. Kill the parent PID (generated in the previous step) when you want the Bot to stop and disconnect.

License

This project is licensed under the MIT License.

Support

If this project has been useful to you, please consider supporting me on Ko-fi or Patreon. It will help me cover the cost of hosting this bot.