LegendsBot
LegendsBot is an experimental project for SAE students to make a bot that serves the needs of a university student. It's designed to be easy to understand, even for those new to programming. This document provides an overview of the setup, execution process, and project structure.
Table of Contents
Getting Started
Prerequisites
- Python (e.g., v3.8 or newer)
- pip (Python package installer, usually comes with Python)
- Visual Studio Code (Optional, but recommended for an easier experience with Python extensions)
- Git (VS Code uses your system's Git installation)
Installation
-
Clone the repository (if you haven't already):
-
Set up a virtual environment (recommended):
python -m venv venv
# On Windows
.\venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate
Tip: VS Code can often help manage virtual environments.
-
Install dependencies: This will read the requirements.txt file and install all the necessary project dependencies into your virtual environment.
python -m pip install -r requirements.txt
Tip: You can open a terminal directly in VS Code (Terminal > New Terminal or `Ctrl+``).\
-
Set up environment variables (if applicable): If the project uses a .env.example file, copy it to .env and fill in your specific configuration details (e.g., API keys, database URLs). The content for the .env file can be found as a pinned message in the SAE Legends Discord channel #uni-legends-bot.
# If .env.example exists
cp .env.example .env
Then, open .env in a text editor and add your environment-specific values.
Running the Project
Python is an interpreted language. The Python files are run directly by the Python interpreter. To run the bot (after activating the virtual environment and setting up .env):
Project Structure
This project follows a typical Python layout. Hereโs what each folder and file does โ explained simply for beginners:
๐ฆ venv/ or .venv/
This is a virtual environment โ a separate space where all the tools (called packages) your bot needs are stored. It helps keep your project organized and avoids conflicts with other Python projects on your system.
โ ๏ธ This folder should not be uploaded to GitHub โ itโs usually listed in .gitignore.
โ๏ธ commands/ or cogs/
This folder contains the commands your bot can respond to on Discord.
Each command gets its own file. For example:
- `` โ Defines the
/add command, which tells the bot to remember something (like a to-do task or reminder).
- `` โ Handles the
/list command. It shows everything the bot has saved using /add.
- `` โ Handles the
/remove command. It lets the bot forget something you've previously added.
๐ requirements.txt
This file lists what your project needs to work (called dependencies). It's a simple text file listing packages and their versions, typically managed with pip.
๐ Pinned versions in requirements.txt
You can "pin" package versions like discord.py==2.3.2 to ensure everyone working on the project uses the exact same version.
๐ Python Files (e.g., main.py, bot.py, deploy_commands.py, config.py)
These are the core files that make the bot run:
or โ The main engine of the bot. It connects to Discord, loads your commands, and listens for activity.
- `` โ A helper script that tells Discord which slash commands your bot offers. Run this when you add or update commands.
- `` โ Stores project settings (like bot token or guild ID), though private stuff should go in
.env.
๐ .env
This file stores private info like your bot token or API keys.
Donโt share it or upload it to GitHub.
โ
If thereโs a .env.example, use it to know what to include in your own .env file.
๐ซ .gitignore
This tells Git which files/folders not to upload to GitHub โ things like:
venv/ (your virtual environment)
__pycache__/ (auto-generated Python files)
.env (your secrets)
๐ README.md
Youโre looking at it!
This file explains what the project does and how to set it up.