HungerLib is a Python automation library purpose-built for Pterodactyl game server panels. Rather than hand-rolling HTTP calls against the Pterodactyl Client API, you import clean Python classes that handle authentication, resource polling, power actions, file management, backups, scheduling, and more. Whether you are building a Discord bot that restarts servers on a schedule, a monitoring dashboard that tracks TPS and RAM, or a deployment script that configures a fresh Minecraft node, HungerLib gives you the building blocks so you can focus on your automation logic instead of raw API plumbing.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerLib/llms.txt
Use this file to discover all available pages before exploring further.
Core Components
HungerLib is composed of several focused modules that work together:| Component | Description |
|---|---|
Panel | The root connection object. Holds your panel URL and API key, exposes ping() / validateAPI() health checks, and owns sub-API modules for schedules, files, backups, databases, startup variables, and commands. |
GenericServer | A universal server wrapper for any Pterodactyl egg. Exposes power actions (start, stop, restart, kill), real-time resource metrics (getRAM, getCPU, getDisk, getUptime), file management, backup management, database management, and schedule management — all scoped to a single server ID. |
MinecraftServer | Extends GenericServer with Minecraft-specific features backed by a running HungerBridge sidecar: live TPS (getTPS), online player count/list (getPlayers), console command execution (sendConsoleCommand), and in-game broadcasts (sendBroadcast). |
BridgeClient | Low-level HTTP client for the HungerBridge v2 REST API. Used internally by MinecraftServer but also accessible directly for custom integrations — supports runCommand, log, getTPS, getPlayers, getPing, getVersion, and more. |
MessageRouter | Structured logging and message routing across multiple servers simultaneously. Routes messages to the terminal (with ASCII color), to each server’s console via HungerBridge, to in-game broadcasts via tellraw, and to rotating log files — all with configurable color-map transforms. |
Validator | Configuration validation engine. Checks config dataclass fields against rules (required, recommended, optional), detects type mismatches, reports fallback usage, and raises typed exceptions (FatalError, TypeMismatchError, FallbackError, RecommendedError) for precise error handling. |
Snapshot | Resource snapshot helper. Captures an instant or time-averaged sample of RAM, CPU, network, disk, TPS, and player count for a given server. Supports smoothing via configurable duration, interval, and drop_outliers. |
Requirements
- Python 3.9 or higher (3.10, 3.11, and 3.12 are tested and supported)
- A running Pterodactyl panel with a valid Client API key
- For
MinecraftServerandBridgeClient: a running HungerBridge sidecar on the target server
Install
| Package | Purpose |
|---|---|
requests | HTTP client for all Pterodactyl and HungerBridge API calls |
mcrcon | RCON protocol support |
PyYAML | YAML configuration file parsing |
mapres | Color-map resolution used by MessageRouter |
Features
Panel
Connect to any Pterodactyl panel. Manage schedules, files, backups, databases, and startup variables through a single authenticated object.
Servers
Control any Pterodactyl server with
GenericServer. Use MinecraftServer for TPS, player lists, and in-game commands.HungerBridge
Real-time Minecraft server introspection via the HungerBridge v2 sidecar API — TPS, players, commands, and console logging.
Scheduler
Snap to cron-aligned schedules, run countdown event chains, and wait for servers to come online or go offline.
MessageRouter
Route structured log messages simultaneously to your terminal, server consoles, in-game broadcasts, and rotating log files.
Validator
Enforce required config fields, detect type mismatches, and surface fallback usage at startup before your automation runs.
License
HungerLib’s
pyproject.toml declares an MIT license and the package is distributed under MIT on PyPI. The GitHub repository may carry a GPL-3.0 header in some source files. Review the repository directly if your project has specific licensing requirements.