200 lines
6.4 KiB
Markdown
Executable File
200 lines
6.4 KiB
Markdown
Executable File
# Discord Bot Project
|
||
|
||
## Overview
|
||
This is a versatile Discord bot project, built using `discord.py`. The bot includes:
|
||
- **Admin Commands** for moderating servers
|
||
- **Economy System** to manage virtual currency
|
||
- **Fun Commands** for interactive experiences
|
||
- **Role Management** to assign roles based on user actions or preferences
|
||
|
||
The bot is structured with scalability in mind, using cogs to separate different functionalities and utilities for common operations.
|
||
|
||
---
|
||
|
||
## Features
|
||
|
||
- **Admin Commands**: Moderation tools such as banning and kicking members.
|
||
- **Economy System**: Tracks user balances and allows users to earn or spend virtual currency.
|
||
- **Fun Commands**: Simple commands that provide entertainment, such as games or random interactions.
|
||
- **Role Management**: Commands that automate role assignments for users.
|
||
|
||
---
|
||
|
||
## Setup
|
||
|
||
### 1. Clone the Repository
|
||
Clone the repository to your local machine:
|
||
```bash
|
||
git clone https://github.com/yourusername/discord-bot.git
|
||
cd discord-bot
|
||
```
|
||
|
||
### 2. Install Requirements
|
||
Install the necessary Python packages listed in `requirements.txt`:
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. Set Up Environment Variables
|
||
The bot requires environment variables for configuration. Create a `.env` file in the root directory and add your Discord bot token:
|
||
```plaintext
|
||
DISCORD_TOKEN=your_token_here
|
||
```
|
||
|
||
### 4. Run the Bot
|
||
Run the bot using the command below:
|
||
```bash
|
||
python bot.py
|
||
```
|
||
|
||
---
|
||
|
||
## Folder Structure
|
||
|
||
Here’s an outline of the directory and file structure for this project:
|
||
|
||
```
|
||
discord-bot/
|
||
│
|
||
├── bot.py
|
||
├── bot_development.py
|
||
├── main.py
|
||
├── dockerfile
|
||
├── requirements.txt
|
||
├── README.md
|
||
├── Fixes.md
|
||
│
|
||
├── cogs/
|
||
│ ├── admin.py
|
||
│ ├── customCommands.py
|
||
│ ├── economy.py
|
||
│ ├── gamble.py
|
||
│ ├── informational.py
|
||
│ ├── listeners.py
|
||
│ ├── mail.py
|
||
│ ├── npc.py
|
||
│ ├── xp.py
|
||
│
|
||
├── utils/
|
||
│ ├── bank_functions.py
|
||
│ ├── npc_data.py
|
||
│ ├── npc_handler.py
|
||
│ ├── npc_memory.py
|
||
│ ├── sql_commands.py
|
||
│
|
||
├── web/
|
||
│ ├── __init__.py
|
||
│ ├── app.py
|
||
│ ├── static/
|
||
│ ├── templates/
|
||
```
|
||
|
||
---
|
||
|
||
## Usage
|
||
|
||
### Commands
|
||
|
||
#### 1. **Admin Commands**
|
||
- `!ban <member> <reason>`: Bans a specified member from the server with an optional reason.
|
||
- `!kick <member> <reason>`: Kicks a specified member from the server with an optional reason.
|
||
|
||
#### 2. **Economy Commands**
|
||
- `!balance`: Check your current balance.
|
||
- `!deposit <amount>`: Deposit a specified amount to your bank.
|
||
- `!withdraw <amount>`: Withdraw a specified amount from your bank.
|
||
|
||
#### 3. **Fun Commands**
|
||
- `!roll <number>`: Rolls a random number up to the specified max.
|
||
- `!8ball <question>`: Provides a magic 8-ball response to your question.
|
||
|
||
#### 4. **Role Management Commands**
|
||
- `!assignrole <role>`: Assigns a role to a user.
|
||
- `!removerole <role>`: Removes a role from a user.
|
||
|
||
### Notes
|
||
- All commands can be customized by modifying their respective cog files in `cogs/`.
|
||
- Admin commands require appropriate permissions (e.g., ban and kick require `Ban Members` or `Kick Members` permissions).
|
||
|
||
---
|
||
|
||
## Configuration
|
||
|
||
### Permissions
|
||
Make sure your bot has the appropriate permissions for each command. You can manage permissions in the [Discord Developer Portal](https://discord.com/developers/applications), where you created your bot. Ensure that:
|
||
- The bot has `Administrator` permissions if needed.
|
||
- `Intents` such as `Message Content`, `Guild Presences`, and `Guild Members` are enabled as required by the bot.
|
||
|
||
### Environment Variables
|
||
Store sensitive information like your bot token in the `.env` file. Avoid committing this file to version control.
|
||
|
||
### Database
|
||
The bot currently uses MySQL for user and balance data through `utils/sql_commands.py` and `utils/bank_functions.py`. You can update these modules if you want to change the database engine or schema.
|
||
|
||
---
|
||
|
||
## Contributing
|
||
|
||
Contributions are welcome! Here’s how you can contribute:
|
||
1. Fork the project.
|
||
2. Create a feature branch (`git checkout -b feature/AmazingFeature`).
|
||
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
|
||
4. Push to the branch (`git push origin feature/AmazingFeature`).
|
||
5. Open a pull request.
|
||
|
||
Make sure to include docstrings for any new functions and comments for complex logic to maintain readability.
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
No license file is included in this repository. Add a `LICENSE` file if you want to make the license explicit.
|
||
|
||
---
|
||
|
||
## Contact
|
||
|
||
For support, please contact [yourname@example.com](mailto:yourname@example.com).
|
||
|
||
Happy Coding!
|
||
|
||
---
|
||
|
||
## Deployment (Web UI)
|
||
|
||
This project includes a small Flask-based web UI used for OAuth flows and guild management. The development server is fine for local testing, but for production use you should run the app under a WSGI server such as `waitress` or `gunicorn`.
|
||
|
||
Recommended steps to serve the web UI with `waitress`:
|
||
|
||
1. Install dependencies (includes `waitress`):
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
2. Set the required environment variables (example `.env`):
|
||
```env
|
||
# Bot and web settings
|
||
TOKEN=your_bot_token_here
|
||
DISCORD_CLIENT_ID=your_client_id
|
||
DISCORD_CLIENT_SECRET=your_client_secret
|
||
DISCORD_REDIRECT_URI=https://yourdomain.com/callback
|
||
|
||
# Flask session secret (must be set in production)
|
||
SECRET_KEY=replace_with_a_secure_random_value
|
||
|
||
# Optional runtime
|
||
START_WEB=1 # set to 1 if you want the bot process to spawn the web UI
|
||
REQUEST_TIMEOUT=10 # default HTTP timeout in seconds for external requests
|
||
```
|
||
|
||
3. Run the web app using `waitress` (example):
|
||
```bash
|
||
python -m waitress --host=0.0.0.0 --port=5000 web.app:app
|
||
```
|
||
|
||
Notes:
|
||
- If you set `START_WEB=1`, `bot_development.py` will spawn the web UI when the bot starts. This is convenient for small deployments but consider running the web UI in its own process or container for reliability and easier scaling.
|
||
- Never run the Flask development server (app.run) in production.
|
||
- Ensure `SECRET_KEY` is kept secret and not committed to source control. Use a secure random value like `openssl rand -hex 32`.
|
||
|
||
If you want, I can add a small `Procfile` and Dockerfile snippet for deployment — tell me which target (Heroku, Docker Compose, or Kubernetes) you prefer. |