pterodactyl-discord-bot/README.md

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
• Installation
• Configuration
• Usage
• Commands
• Embed System
• Permissions
• Logging
• Troubleshooting
• Contributing
• 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 to restrict access
• Persistent Storage: Remembers embeds and recreates them 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:

   git clone https://git.serendipity.systems/yourusername/pterodactyl-discord-bot.git
   cd pterodactyl-discord-bot
   

2. Install required dependencies:

   pip install -r requirements.txt
   

3. Create a config.ini file (see Configuration section)

4. Run the bot:

   python pterodisbot.py
   

Configuration

The bot requires a config.ini file with the following structure:

[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 whenever server status changes or CPU usage spikes up/down for more than 10 seconds
5. Create power control buttons for each Pterodactyl server monitored

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:

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:

   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 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.