Update "Features"
k.eaven committed
1 parent
2b15333bb6
commit
369560ac8b
1 file changed
+248
+248
@@ -0,0 +1,248 @@
|
||||
# Features
|
||||
|
||||
## Overview
|
||||
|
||||
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:
|
||||
```json
|
||||
{
|
||||
"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 |
|
||||
|
||||
---
|
||||
|
||||
## Related Pages
|
||||
|
||||
- [Architecture](/Architecture) - System design and data flow
|
||||
- [Installation](/Installation) - Deployment guides
|
||||
- [Configuration](/Configuration) - Config options
|
||||
- [Usage](/Usage) - Commands and workflows
|
||||
- [Contributing](/Contributing) - Development guidelines
|
||||
Reference in new issue
Block a user