Create README
This commit is contained in:
193
README.md
193
README.md
@@ -1,2 +1,193 @@
|
|||||||
# pterodactyl-discord-bot
|
# Pterodactyl Discord Bot
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
A comprehensive Discord bot for managing Pterodactyl game servers through Discord, providing real-time status monitoring and control capabilities.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
- [Features](#features)
|
||||||
|
- [Installation](#installation)
|
||||||
|
- [Configuration](#configuration)
|
||||||
|
- [Usage](#usage)
|
||||||
|
- [Commands](#commands)
|
||||||
|
- [Embed System](#embed-system)
|
||||||
|
- [Permissions](#permissions)
|
||||||
|
- [Logging](#logging)
|
||||||
|
- [Troubleshooting](#troubleshooting)
|
||||||
|
- [Contributing](#contributing)
|
||||||
|
- [License](#license)
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Real-time Server Monitoring**: Auto-updating embeds showing server status and resource usage
|
||||||
|
- **Power Controls**: Start, stop, and restart servers directly from Discord
|
||||||
|
- **Connection Info**: Display server IP addresses and ports with one click
|
||||||
|
- **Multi-channel Support**: Status embeds can be placed in any channel
|
||||||
|
- **Smart Updates**: Only updates embeds when significant changes occur
|
||||||
|
- **Role-based Access Control**: Restrict server controls to users with specific roles
|
||||||
|
- **Single-guild Operation**: Designed for use in one Discord server
|
||||||
|
- **Persistent Storage**: Remembers embed locations between bot restarts
|
||||||
|
- **Comprehensive Logging**: Detailed logs for all operations and errors
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Prerequisites
|
||||||
|
- Python 3.8 or higher
|
||||||
|
- Discord bot token with proper permissions
|
||||||
|
- Pterodactyl panel with API access
|
||||||
|
- Server with Client and Application API keys
|
||||||
|
|
||||||
|
### Setup Steps
|
||||||
|
|
||||||
|
1. Clone the repository:
|
||||||
|
```bash
|
||||||
|
git clone https://github.com/yourusername/pterodactyl-discord-bot.git
|
||||||
|
cd pterodactyl-discord-bot
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Install required dependencies:
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Create a `config.ini` file (see [Configuration](#configuration) section)
|
||||||
|
|
||||||
|
4. Run the bot:
|
||||||
|
```bash
|
||||||
|
python pterodisbot.py
|
||||||
|
```
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
The bot requires a `config.ini` file with the following structure:
|
||||||
|
|
||||||
|
```ini
|
||||||
|
[Pterodactyl]
|
||||||
|
PanelURL = https://your.pterodactyl.panel
|
||||||
|
ClientAPIKey = ptlc_yourclientkey
|
||||||
|
ApplicationAPIKey = ptla_yourapplicationkey
|
||||||
|
|
||||||
|
[Discord]
|
||||||
|
Token = your.discord.bot.token
|
||||||
|
AllowedGuildID = 123456789012345678
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Details
|
||||||
|
|
||||||
|
- **PanelURL**: Your Pterodactyl panel URL (must include http:// or https://)
|
||||||
|
- **ClientAPIKey**: Pterodactyl client API key (starts with `ptlc_`)
|
||||||
|
- **ApplicationAPIKey**: Pterodactyl application API key (starts with `ptla_`)
|
||||||
|
- **Token**: Your Discord bot token
|
||||||
|
- **AllowedGuildID**: The Discord server ID where the bot should operate
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
Once configured and running, the bot will:
|
||||||
|
|
||||||
|
1. Connect to your Discord server
|
||||||
|
2. Sync slash commands
|
||||||
|
3. Begin monitoring your Pterodactyl servers
|
||||||
|
4. Update status embeds every 10 seconds (configurable)
|
||||||
|
|
||||||
|
### First Run
|
||||||
|
|
||||||
|
On first run, you'll need to manually create status embeds using the `/server_status` command for each server you want to monitor.
|
||||||
|
|
||||||
|
## Commands
|
||||||
|
|
||||||
|
### `/server_status [server_name] [channel]`
|
||||||
|
Display a server's status embed in the specified channel (or current channel if not specified).
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
```
|
||||||
|
/server_status server_name: "Minecraft Survival" channel: #game-servers
|
||||||
|
```
|
||||||
|
|
||||||
|
### `/refresh_embeds` (Admin only)
|
||||||
|
Force a refresh of all server status embeds. This is useful if embeds become out of sync.
|
||||||
|
|
||||||
|
## Embed System
|
||||||
|
|
||||||
|
The bot uses persistent interactive embeds with the following features:
|
||||||
|
|
||||||
|
- **Dynamic Color Coding**: Running (blue) vs offline (red)
|
||||||
|
- **Resource Monitoring**: CPU, memory, disk, and network usage
|
||||||
|
- **Interactive Buttons**:
|
||||||
|
- Start (green)
|
||||||
|
- Stop (red)
|
||||||
|
- Restart (blue)
|
||||||
|
- Show Address (grey)
|
||||||
|
|
||||||
|
Embed locations are stored in `embed_locations.json` and persist between bot restarts.
|
||||||
|
|
||||||
|
## Permissions
|
||||||
|
|
||||||
|
The bot implements two levels of access control:
|
||||||
|
|
||||||
|
1. **Guild Restriction**: Only works in the Discord server specified in `AllowedGuildID`
|
||||||
|
2. **Role Requirement**: Users must have the "Game Server User" role to interact with server controls
|
||||||
|
|
||||||
|
Administrators can use the `/refresh_embeds` command.
|
||||||
|
|
||||||
|
## Logging
|
||||||
|
|
||||||
|
The bot maintains comprehensive logs in two locations:
|
||||||
|
|
||||||
|
1. **File Logs**: Rotating log files (5MB max, 3 backups) in `pterodactyl_bot.log`
|
||||||
|
2. **Console Output**: Real-time logging to stdout
|
||||||
|
|
||||||
|
Log levels include:
|
||||||
|
- DEBUG: Detailed operational information
|
||||||
|
- INFO: General operational messages
|
||||||
|
- WARNING: Potential issues
|
||||||
|
- ERROR: Operational failures
|
||||||
|
- CRITICAL: Critical failures
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
|
||||||
|
1. **Embeds not updating**:
|
||||||
|
- Check bot has proper permissions in the channel
|
||||||
|
- Verify API keys are correct and have proper permissions
|
||||||
|
- Use `/refresh_embeds` to reset all embeds
|
||||||
|
|
||||||
|
2. **Buttons not working**:
|
||||||
|
- Ensure users have the "Game Server User" role
|
||||||
|
- Verify the bot has proper permissions (View Channel, Send Messages, Embed Links)
|
||||||
|
|
||||||
|
3. **API errors**:
|
||||||
|
- Check your Pterodactyl panel URL and API keys
|
||||||
|
- Verify the server exists in Pterodactyl
|
||||||
|
|
||||||
|
### Checking Logs
|
||||||
|
|
||||||
|
Always check the log files first when troubleshooting:
|
||||||
|
```bash
|
||||||
|
tail -f pterodactyl_bot.log
|
||||||
|
```
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Contributions are welcome! Please follow these guidelines:
|
||||||
|
|
||||||
|
1. Fork the repository
|
||||||
|
2. Create a feature branch
|
||||||
|
3. Submit a pull request
|
||||||
|
|
||||||
|
### Development Setup
|
||||||
|
|
||||||
|
1. Install development dependencies:
|
||||||
|
```bash
|
||||||
|
pip install -r requirements-dev.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Enable debug logging by modifying the logger configuration in the bot code.
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Note**: This bot is designed for use with a single Pterodactyl domain and single Discord server. For multi-domain or multi-guild support, modifications would be required.
|
||||||
Reference in New Issue
Block a user