Pterodisbot provides a comprehensive suite of features for monitoring and managing Pterodactyl game servers through Discord. This page documents each feature in detail.

🎮 Server Management

Interactive Server Selection

Dropdown Menu: /server_status command displays an intuitive dropdown with all available game servers
Server Information: Each option shows server name and description (truncated to 50 chars)
Statistics Dashboard: Shows total servers, online count, and offline count before selection

Real-time Power Controls

Color-coded button controls for server power management:

🟢 Green Start Button - Powers on the server
🔴 Red Stop Button - Gracefully shuts down the server
🔵 Blue Restart Button - Reboots the server
⚪ Grey Show Address Button - Displays connection information (IP:Port)

Connection Information

Instantly view server IP addresses and ports
Fetches default allocation from Pterodactyl panel
Displayed in ephemeral embed (private to requesting user)

Multi-channel Embeds

Deploy server status displays across any channels where the bot has permissions
Each server can have one active embed at a time
Automatic cleanup of previous embeds when recreating

📊 Server Monitoring

Live Status Tracking

Auto-updating embeds display current server state (online/offline/starting)
Color-coded status: 🔵 Blue for online, 🔴 Red for offline
Last updated timestamp on every embed

Resource Usage Metrics

Real-time monitoring of:

Metric	Description
CPU Usage	Percentage with dynamic scaling for multi-core servers
Memory Consumption	Current usage vs. allocated limit (MiB)
Disk Space	Current usage vs. allocated limit (MiB)
Network Activity	Incoming/outgoing traffic (MiB)
Uptime Counter	Human-readable formatting (seconds, minutes, hours, days)

Visual Metrics Graphs

Combined CPU and Memory Graphs over the last minute
6 data points captured at 10-second intervals
Discord dark theme-optimized styling (#2f3136 background)
Automatic graph generation and embedding for running servers
Dynamic CPU scaling (100% increments) for accurate multi-vCPU visualization
Trend indicators (increasing/decreasing/stable) for quick status assessment

🔄 Intelligent Update System

Smart Update Triggers

Embeds refresh automatically when:

Trigger	Condition
Power State Change	Server transitions between offline ↔ starting ↔ running
Significant CPU Change	CPU usage shifts by more than 50%
First Detection	Server detected for the first time
Periodic Uptime	Running servers reach 10-minute intervals

Rate Limit Protection

Built-in delays (0.5s between servers, 1s during refresh) prevent Discord API throttling
Optimized API calls minimize unnecessary requests through change detection
Background task management with asynchronous update loop running every 10 seconds

🔒 Security & Access Control

Single-Guild Restriction

Bot operates exclusively in your designated Discord server (AllowedGuildID)
All interactions from other guilds are rejected with ephemeral message

Role-based Permissions

"Game Server User" role required for all server interactions
Exact name match required (case-sensitive)
Role used purely for access control - no special Discord permissions needed

Administrator Commands

Special management commands restricted to server administrators
/refresh_embeds - Force refresh all embeds
/purge_embeds - Permanently delete all embeds

Interaction Validation

Every button press and command verified for proper authorization
Guild check + role check on every interaction
Ephemeral error messages for unauthorized attempts

💾 Data Persistence

Embed Location Storage

Automatically remembers where embeds are posted
Survives bot restarts and crashes
Stored in embed/embed_locations.json

JSON-based Storage

Human-readable embed tracking format:

{
  "server_identifier": {
    "channel_id": "123456789012345678",
    "message_id": "987654321098765432"
  }
}

Metrics History

Maintains 1 minute of server metrics data (6 data points per server)
Automatic FIFO rotation using deque(maxlen=6)
In-memory only (cleared on restart)

Automatic Cleanup

Removes tracking for deleted embeds (Discord NotFound errors)
Cleans up metrics for servers that no longer exist in panel
Runs during each update cycle

🛡️ Reliability Features

Comprehensive Error Handling

Graceful recovery from API failures and network issues
Failed embed updates logged but don't crash the update cycle
Structured exception hierarchy for different failure modes

Rotating Log Files

Automatic log rotation when file reaches 5MB
Keeps 3 previous log files (pterodisbot.log.1, .2, .3)
UTF-8 encoding for international character support

Debug-level Logging

Detailed operational logs for troubleshooting
API calls, state changes, cache operations at DEBUG level
General operations at INFO level

Graceful Shutdown

Proper cleanup on SIGINT/SIGTERM signals (Docker-friendly)
Saves embed locations before shutdown
Closes API sessions cleanly

Configuration Validation

Startup verification of all required settings
API key format validation (ptlc_/ptla_ or pacc_/papp_)
URL protocol validation (http:// or https://)
Guild ID integer validation

API Key Validation

Checks for correct Pterodactyl API key formats
Validates both client and application keys at startup
Clear error messages for misconfigured keys

🎨 User Interface

Color-coded Status

🔵 Blue for online/running servers
🔴 Red for offline/stopped servers
Embed titles reflect current state

Ephemeral Interactions

Private responses visible only to command users
/server_status dashboard is ephemeral
Button responses are ephemeral
Address display is ephemeral

Real-time Feedback

Instant confirmation messages for all actions
Start/Stop/Restart show "is starting...", "is stopping...", "is restarting..."
Error messages include API response details

Persistent Controls

Server control buttons remain functional indefinitely
Views created with timeout=None for infinite persistence
Survives bot restarts (re-registered on startup)

Responsive Design

Clean, Discord-optimized embed layouts
Code-block formatting for resource usage tables
Proper field inline/block arrangement

🔧 Administrator Tools

Bulk Embed Refresh (`/refresh_embeds`)

Force-refresh all server status embeds with one command
Recreates all tracked embeds with fresh data
Deletes old embed messages to prevent duplication
Updates embed tracking storage
Provides statistics on deleted and created embeds

Complete Purge System (`/purge_embeds`)

Remove all bot embeds from the server with detailed statistics
Real-time progress updates during multi-embed operations
Shows deleted, missing, and error counts
Success rate percentage calculation
Clears embed tracking file

Progress Tracking

Real-time progress updates during multi-embed operations
Updates every 5 embeds processed
Ephemeral progress embed with live counters

Comprehensive Logging

All administrative actions logged with user attribution
Command invocation, success/failure, statistics

Feature Comparison Table

Feature	Traditional	Docker	Kubernetes
Server Management	✅	✅	✅
Real-time Monitoring	✅	✅	✅
Metrics Graphs	✅	✅	✅
Role-based Access	✅	✅	✅
Persistent Embeds	✅	✅	✅
Admin Tools	✅	✅	✅
Auto-restart	Manual	`--restart unless-stopped`	`restartPolicy: Always`
Log Persistence	Local files	Volume mount	PVC
Config Management	config.ini	Env vars / Volume	Secrets
Scaling	Manual	Manual	HPA support

Architecture - System design and data flow
Installation - Deployment guides
Configuration - Config options
Usage - Commands and workflows
Contributing - Development guidelines

Features

Overview