# Pterodactyl Discord Bot

![Pterodactyl Logo](https://cdn.pterodactyl.io/logos/new/pterodactyl_logo_transparent.png)

A feature-rich Discord bot for monitoring and managing Pterodactyl game servers through Discord, providing real-time status monitoring and control capabilities with an intuitive interface.

## Table of Contents
- [Features](#features)
- [Architecture Overview](#architecture-overview)
- [Installation](#installation)
  - [Traditional Installation](#traditional-installation)
  - [Docker Installation](#docker-installation)
- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [Configuration File](#configuration-file)
- [Usage](#usage)
  - [First Run Setup](#first-run-setup)
  - [Bot Commands](#bot-commands)
  - [Embed System](#embed-system)
- [Permissions](#permissions)
- [Logging System](#logging-system)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## Features

### Core Functionality
- **Real-time Server Monitoring**: Auto-updating embeds showing server status (online/offline) and detailed resource usage
- **Power Management**: Start, stop, and restart servers directly from Discord with button controls
- **Connection Information**: One-click display of server IP addresses and ports
- **Multi-channel Support**: Status embeds can be placed in any channel with proper permissions

### Intelligent Updates
- **State Change Detection**: Embeds update immediately when server power state changes
- **Resource Thresholds**: CPU usage changes >50% trigger updates
- **Optimized API Calls**: Minimizes requests to the Discord API

### Access Control
- **Guild Restriction**: Operates only in specified Discord server
- **Role-based Permissions**: "Game Server User" role required for interactions
- **Admin Commands**: Special commands restricted to server administrators

### Reliability Features
- **Persistent Storage**: Remembers embed locations between bot restarts
- **Error Handling**: Comprehensive error recovery and logging
- **Rate Limit Protection**: Built-in delays between API calls

## Architecture Overview

The bot is built with several key components:

1. **PterodactylAPI Class**: Handles all communication with the Pterodactyl Panel API
2. **ServerStatusView Class**: Manages the interactive Discord UI with control buttons
3. **PterodactylBot Class**: Main bot class that orchestrates all operations
4. **Background Task**: Regularly checks server status and updates embeds when needed
5. **Configuration System**: Validates and manages all settings from config.ini

The system uses aiohttp for asynchronous HTTP requests and discord.py for Discord interactions.

## Installation

### Prerequisites
- Python 3.8 or higher **or** Docker
- Discord bot token with proper permissions
- Pterodactyl panel with API access
- Server with both Client and Application API keys

### Traditional Installation

1. Clone the repository:
   ```bash
   git clone https://git.serendipity.systems/yourusername/pterodactyl-discord-bot.git
   cd pterodactyl-discord-bot
   ```

2. Install required dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. Create and configure your `config.ini` file (see [Configuration](#configuration) section)

4. Run the bot:
   ```bash
   python pterodisbot.py
   ```

### Docker Installation

1. Build the Docker image:
   ```bash
   docker build -t pterodactyl-bot .
   ```

2. Create a directory for configuration:
   ```bash
   mkdir -p bot-config
   ```

3. Create a `config.ini` file in the `bot-config` directory with your settings

4. Run the container with the config mounted:
   ```bash
   docker run -d \
     --name pterodactyl-bot \
     -v $(pwd)/bot-config:/app \
     pterodactyl-bot
   ```

5. For Docker Compose, create a `docker-compose.yml` file:
   ```yaml
   services:
     pterodisbot:
       build: .
         environment:
           # Remmove brackets and spaces in environment variables
           # Ideally, use .env file to assign values to these instead
           - DISCORD_TOKEN={Your Discord bot token}
           - ALLOWED_GUILD_ID={The Discord server ID where the bot should operate}
           - PANEL_URL={Your Pterodactyl panel URL (must include http:// or https://)}
           - CLIENT_API_KEY={Pterodactyl client API key (starts with `ptlc_`)}
           - APPLICATION_API_KEY={Pterodactyl application API key (starts with `ptla_`)}
       volumes:
         - bot_logs:/app/logs
         - bot_embed:/app/embed
       restart: unless-stopped
    
   volumes:
     bot_logs:
     bot_embed:
   ```
   Then run:
   ```bash
   docker-compose up -d
   ```

## Configuration

### Environment Variables

When using Docker or generating the config automatically, these environment variables are required:

- `DISCORD_TOKEN`: Your Discord bot token
- `ALLOWED_GUILD_ID`: The Discord server ID where the bot should operate
- `PANEL_URL`: Your Pterodactyl panel URL (must include http:// or https://)
- `CLIENT_API_KEY`: Pterodactyl client API key (starts with `ptlc_`)
- `APPLICATION_API_KEY`: Pterodactyl application API key (starts with `ptla_`)

### Configuration File

The bot uses a `config.ini` file with this structure:

```ini
[Pterodactyl]
PanelURL = https://your.pterodactyl.panel
ClientAPIKey = ptlc_yourclientkey
ApplicationAPIKey = ptla_yourapplicationkey

[Discord]
Token = your.discord.bot.token
AllowedGuildID = 123456789012345678
```

To generate the config file from environment variables:
```bash
python generate_config.py
```

## Usage

### First Run Setup

1. Invite your bot to your Discord server with these permissions:
   - View Channels
   - Send Messages
   - Embed Links
   - Manage Messages (for embed updates)
   - Use Slash Commands

2. Create a "Game Server User" role for users who should control servers

3. Use the `/server_status` command to create your first status embed

### Bot 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

Status embeds include:
- Server name and current state (color-coded)
- Resource usage (when online):
  - CPU percentage
  - Memory usage
  - Disk usage
  - Network activity
- 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 System

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:
- **DEBUG**: Detailed operational information (API calls, state changes)
- **INFO**: General operational messages (bot startup, command usage)
- **WARNING**: Potential issues (missing embeds, API warnings)
- **ERROR**: Operational failures (API errors, permission issues)
- **CRITICAL**: Critical failures (configuration errors, startup failures)

## Troubleshooting

### Common Issues

**Embeds not updating:**
- Verify the bot has proper channel permissions
- Check API keys have correct permissions
- Use `/refresh_embeds` to reset all embeds

**Buttons not working:**
- Confirm users have the "Game Server User" role
- Ensure the bot has these permissions:
  - View Channel
  - Send Messages
  - Embed Links
  - Use Slash Commands

**API errors:**
- Double-check your Pterodactyl panel URL
- Verify API keys are correct and not expired
- Confirm the server exists in Pterodactyl

### Checking Logs

For real-time log monitoring:
```bash
tail -f pterodactyl_bot.log
```

## Development

### Requirements
- Python 3.8+
- Poetry (recommended) or pip

### Setup
1. Clone the repository
2. Install dependencies:
   ```bash
   poetry install
   ```
   or
   ```bash
   pip install -r requirements.txt -r requirements-dev.txt
   ```

3. Create a `.env` file with your development environment variables

4. Run in development mode:
   ```bash
   python pterodisbot.py
   ```

### Testing
The project includes unit tests (to be expanded). Run with:
```bash
pytest
```

## Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin feature/your-feature`)
5. Open a pull request

### Coding Standards
- Follow PEP 8 style guidelines
- Include type hints for all function signatures
- Document public methods with docstrings
- Write tests for new functionality

## License

This project is licensed under the GPL-3.0 License - see the [LICENSE](LICENSE) file for details.

---

**Note**: This bot is designed for single Pterodactyl domain and single Discord guild use. For multi-instance support, significant modifications would be required.