k.eaven/Pterodisbot

0 Fork 0

Table of Contents

Usage

Overview
First Run Setup
Bot Commands

/server_status
/refresh_embeds (Admin Only)
/purge_embeds (Admin Only)

Embed System

Header Information
Status Fields
Resource Usage (When Online)
Metrics Visualization (When Running)
Interactive Buttons
Automatic Updates
Embed Persistence

Permissions

1. Guild Restriction
2. Role-Based Access
3. Administrator Access

Logging System

File Logs
Console Output
Log Levels
Example Log Entries
Checking Logs

Workflow Examples

Daily Server Management
Admin Maintenance
Cleanup

Troubleshooting Common Issues

Embeds not updating
Buttons not working
Commands not appearing
Graphs not appearing

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

Usage

Overview

This page documents how to use Pterodisbot after installation, including first-run setup, commands, and the embed system.

First Run Setup

Ensure bot is invited to your Discord server with proper permissions (see Discord Bot Setup)
Verify "Game Server User" role exists in your server with exact name match

Start the bot using your preferred installation method:

# Traditional
python main.py

# Docker
docker-compose up -d

# Kubernetes
kubectl apply -f deployment.yaml

Bot should appear online in your server
Use /server_status to create your first status embed

Bot Commands

`/server_status`

Display an interactive dropdown menu containing all available servers from your Pterodactyl panel. Select a server to create a permanent status embed in the current channel with real-time monitoring and control buttons.

Features:

Shows total server count and online/offline statistics
Lists all servers with descriptions
Creates persistent, auto-updating embeds
Automatically removes old embeds when recreating for the same server

Usage:

Type /server_status in any channel where the bot has permissions
Select a server from the dropdown menu (ephemeral - only you see it)
The server's status embed is posted in the current channel
Anyone with the "Game Server User" role can interact with the embed

Example Output:

🏗️ Server Status Dashboard
Select a server from the dropdown below to view its detailed status and controls.

📊 Server Statistics
Total Servers: 5
✅ Online: 3
❌ Offline: 2

ℹ️ How to Use
Use the dropdown menu below to select a server. The server's status embed will be posted in this channel.

[Dropdown: Select a server to display... ▼]

`/refresh_embeds` (Admin Only)

Force a complete refresh of all server status embeds. Requires Administrator permission.

What it does:

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

Use Cases:

Embeds appear out of sync with actual server states
After bot configuration changes
Following Discord API issues

Example Output:

Refreshed all embeds. Deleted 5 old embeds, created 5 new ones.

`/purge_embeds` (Admin Only)

Permanently delete all server status embeds from the Discord server. Requires Administrator permission.

What it does:

Removes all tracked embed messages
Clears the embed tracking file
Provides real-time progress updates
Shows detailed statistics (deleted, missing, errors)

Use Cases:

Starting fresh with new embed layout
Removing bot from server
Cleaning up after testing

Example Progress:

🔄 Purging Server Embeds
Processing 5 embeds...
Deleted: 2 | Not Found: 1 | Errors: 0

Example Result:

✅ Embed Purge Complete
Total Tracked: 5
✅ Successfully Deleted: 3
❌ Already Missing: 1
⚠️ Errors: 1
📊 Success Rate: 80.0%
Embed tracking file has been cleared

Embed System

Status embeds dynamically display comprehensive server information with interactive controls.

Header Information

Server name with current state (color-coded)
Server description from Pterodactyl panel
Last updated timestamp (auto-updates)

Status Fields

Field	Description
🆔 Server ID	Pterodactyl identifier (backtick formatted)
ℹ️ Status	Active ✅ or Suspended ⛔
⏱️ Uptime	Human-readable (for running servers)

Resource Usage (When Online)

Formatted as a properties-style code block:

properties
CPU    : [   15.50 /     100 %]
Memory : [  1024.00 /    4096 MiB]
Disk   : [  5120.00 /   20480 MiB]

Additional network fields:

Network In 📥: Incoming traffic (MiB)
Network Out 📤: Outgoing traffic (MiB)

Metrics Visualization (When Running)

Combined CPU and Memory Graph showing last 1 minute:

6 data points at 10-second intervals
Discord dark theme optimized
Dynamic CPU scaling (100% increments for multi-vCPU)
Trend indicators (increasing/decreasing/stable)
Data point counter (X/6)

Graph Fields:

📈 Usage Trends (Last Minute)
>>> `Data points: 4/6`
`CPU trend: stable • Memory trend: increasing`

[Graph image attached]

Interactive Buttons

Button	Style	Action	Permission Required
Start	🟢 Green	Powers on the server	Game Server User
Stop	🔴 Red	Gracefully shuts down	Game Server User
Restart	🔵 Blurple	Reboots the server	Game Server User
Show Address	⚪ Grey	Displays IP:Port	Game Server User

Button Responses (ephemeral - private to user):

Success: "Server 'Name' is starting..."
Error: "Failed to start server: [API error message]"

Automatic Updates

Embeds refresh when server state changes:

Power state transitions (offline ↔ starting ↔ running)
Significant resource usage changes (CPU >50% shift)
Periodic updates for uptime accuracy (every 10 minutes for running servers)
Rate limit protection with built-in delays

Embed Persistence

Locations stored in embed/embed_locations.json
Survives bot restarts and crashes
Format:

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

Permissions

1. Guild Restriction

The bot only responds to commands and interactions from the Discord server specified in AllowedGuildID. This prevents unauthorized use if the bot is accidentally added to other servers.

2. Role-Based Access

Users must have the "Game Server User" role (exact name match) to:

Use server control buttons (Start/Stop/Restart)
View server addresses
Interact with any bot features

3. Administrator Access

Server administrators (users with Discord's Administrator permission) can additionally:

Use /refresh_embeds command
Use /purge_embeds command
No special role required - based on Discord permissions

Note: The /server_status command can be used by anyone, but only users with the "Game Server User" role can interact with the resulting embeds.

Logging System

File Logs

Location: logs/pterodisbot.log
Rotation: Automatic rotation when file reaches 5MB
Backups: Keeps 3 previous log files (pterodisbot.log.1, .2, .3)
Format: YYYY-MM-DD HH:MM:SS - LEVEL - MESSAGE

Console Output

Real-time: Logs appear in stdout/stderr
Format: Same as file logs
Level: INFO and above (less verbose than file logs)

Log Levels

Level	Description
DEBUG	Detailed operational information (API calls, state changes, cache operations)
INFO	General operational messages (bot startup, command usage, successful operations)
WARNING	Potential issues (missing embeds, API warnings, permission issues)
ERROR	Operational failures (API errors, Discord API issues, failed operations)
CRITICAL	Critical failures (configuration errors, startup failures, unrecoverable errors)

Example Log Entries

2025-09-29 03:51:13,743 - INFO - Initialized logging system with file and console output
2025-09-29 03:51:16,828 - INFO - Starting full refresh of all server embeds
2025-09-29 03:51:16,829 - INFO - Bot connected as Petrodisbot (ID: 1419694924458360964)
2025-09-29 03:52:10,481 - INFO - Start button pressed for Minecraft Server by username
2025-09-29 03:52:14,406 - DEBUG - Power state changed for Minecraft Server: offline -> starting

Checking Logs

Real-time monitoring:

# Traditional installation
tail -f logs/pterodisbot.log

# Docker installation
docker logs -f pterodisbot

# Docker Compose
docker-compose logs -f pterodisbot

# Kubernetes
kubectl logs -n pterodisbot -l app=pterodisbot -f

Searching logs:

# Find all ERROR level messages
grep "ERROR" logs/pterodisbot.log

# Find logs for specific server
grep "Server_Name" logs/pterodisbot.log

# View last 100 lines
tail -n 100 logs/pterodisbot.log

Workflow Examples

Daily Server Management

User types /server_status
Selects "Minecraft Server" from dropdown
Embed appears in channel with current status
User clicks "Start" button → server starts
Embed auto-updates to "Running" with metrics
User clicks "Show Address" → gets IP:Port privately

Admin Maintenance

Admin notices embeds out of sync
Types /refresh_embeds
All embeds recreated with fresh data
Statistics shown: "Deleted 3 old embeds, created 3 new ones"

Cleanup

Admin wants to remove all bot embeds
Types /purge_embeds
Progress embed shows real-time deletion
Final result shows success rate
Embed tracking file cleared

Troubleshooting Common Issues

Embeds not updating

Verify bot has channel permissions (View Channel, Send Messages, Embed Links)
Check both API keys are valid
Review logs for API errors
Use /refresh_embeds to force-recreate

Buttons not working

Confirm users have "Game Server User" role (exact name)
Verify role assignment
Check bot permissions include "Use Slash Commands"
Ensure interaction is in correct guild

Commands not appearing

Wait 5-10 minutes after startup (command sync takes time)
Verify "Use Slash Commands" permission
Check bot is in correct guild
Review logs for sync errors

Graphs not appearing

Wait 20+ seconds after server starts (needs 2 data points)
Verify server is "running" state
Check matplotlib installation
Review logs for graph generation errors

Architecture - System design
Installation - Deployment guides
Configuration - Config options
Features - Feature details
Contributing - Development guidelines