Skip to main content

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.

MinecraftServer extends GenericServer with Minecraft-specific capabilities powered by the HungerBridge v2 API. In addition to the full Pterodactyl control surface inherited from GenericServer, it connects to a running HungerBridge plugin instance to expose live TPS readings, online player counts and names, authenticated console command execution, and tellraw broadcasts — all without opening a WebSocket console. A BridgeClient instance is created automatically during construction and stored at self.bridge. You can call self.bridge methods directly for lower-level access. 
from hungerlib import Panel
from hungerlib.servers import MinecraftServer

panel = Panel("production", "https://panel.example.com", "ptlc_xxxx")

mc = MinecraftServer(
    name="survival",
    panel=panel,
    server_id="a1b2c3d4",
    server_domain="mc.example.com",
    server_port=25565,
    bridge_port=8080,
    bridge_token="my-secret-token",
)

print(mc.getTPS())           # e.g. 19.982
print(mc.getPlayers())       # e.g. 7
mc.sendBroadcast("Server restarting in 5 minutes!")

​
Constructor

MinecraftServer(
    name: str,
    panel: Panel,
    server_id: str,
    server_domain: str,
    server_port: int,
    bridge_port: int,
    bridge_token: str,
)
​
name
str
required
Human-readable label for this server. Passed through to GenericServer.
​
panel
Panel
required
Authenticated Panel instance. Passed through to GenericServer for all Pterodactyl API calls.
​
server_id
str
required
Pterodactyl server short UUID. Passed through to GenericServer.
​
server_domain
str
required
Hostname or IP address where the Minecraft server is reachable, e.g. "mc.example.com" or "10.0.0.5". Used to construct the HungerBridge base URL and stored as self.server_domain.
​
server_port
int
required
The Minecraft game port (typically 25565). Stored as self.server_port for reference; not used internally for bridge communication.
​
bridge_port
int
required
The port that the HungerBridge HTTP API is listening on. Combined with server_domain to build http://{server_domain}:{bridge_port} and passed to the BridgeClient constructor.
​
bridge_token
str
required
The X-Auth-Key token configured in HungerBridge. Passed directly to BridgeClient.
After construction, self.bridge holds the BridgeClient instance for direct low-level access.

​
Minecraft Methods

​
getPlayers()

mc.getPlayers(mode: str = "count") -> int | list | None
Queries the HungerBridge /v2/players endpoint and returns either a count or a list of online player names.
​
mode
str
default:"count"
Controls what is returned:
  • "count" — returns the integer number of online players.
  • "list" — returns a list[str] of online player usernames.
Returns int when mode="count", list[str] when mode="list", or None if the bridge is unreachable. Raises InvalidModeError if mode is not "count" or "list". 
count = mc.getPlayers("count")   # 7
names = mc.getPlayers("list")    # ["Steve", "Alex", "Notch"]

​
getTPS()

mc.getTPS(mode: str = "current", rounding: int = 3) -> float | None
Returns the server’s TPS (ticks per second) from the HungerBridge /v2/tps endpoint. Returns None silently on invalid mode rather than raising, making it safe to call in monitoring loops.
​
mode
str
default:"current"
Which TPS measurement to return. Maps directly to BridgeClient.getTPS(mode):
  • "current" — EMA20, the smoothed near-real-time TPS.
  • "1m" — EMA over the last ~1200 ticks (≈1 minute).
  • "5m" — EMA over the last ~6000 ticks (≈5 minutes).
  • "tick_time" — Average tick duration in milliseconds.
​
rounding
int
default:"3"
Number of decimal places to round the result to. Pass None to skip rounding.
Returns float rounded to rounding places, or None if the mode is invalid or the bridge returns no data. 
print(mc.getTPS())           # 19.982  (current EMA20)
print(mc.getTPS("5m"))       # 19.755  (5-minute average)
print(mc.getTPS("tick_time")) # 1.243  (ms per tick)

​
sendConsoleCommand()

mc.sendConsoleCommand(
    command: str,
    show_console: bool = False,
    silent: bool = False,
    normalize: bool = True,
) -> str | dict | None
Executes a command on the Minecraft server through HungerBridge and optionally returns its output. Delegates directly to BridgeClient.runCommand().
​
command
str
required
The Minecraft server command to execute, without a leading /, e.g. "op Steve" or "say Hello".
​
show_console
bool
default:"False"
When True, the command and its output are echoed to the server console log.
​
silent
bool
default:"False"
When True, suppresses any in-game feedback messages produced by the command.
​
normalize
bool
default:"True"
When True (default), output lines are joined into a single str. When False, the raw bridge response dict is returned.
Returns str of normalised output when normalize=True, the raw dict response when normalize=False, or None if the bridge returns no output. 
output = mc.sendConsoleCommand("list", show_console=True)
print(output)  # "There are 3 of a max of 20 players online: Steve, Alex, Notch"

​
sendBroadcast()

mc.sendBroadcast(message: str) -> str | dict | None
Sends a tellraw @a command to display a message to all online players. Double-quotes in message are automatically escaped.
​
message
str
required
The plain-text message to broadcast to all players. Do not include JSON formatting — the method wraps the text in a minimal tellraw JSON object.
Returns The normalised output of the underlying tellraw command (typically an empty string or None). 
mc.sendBroadcast("Welcome to the server!")
mc.sendBroadcast("Restarting in 60 seconds...")

​
Inherited Methods

MinecraftServer inherits every method from GenericServer without modification. Refer to the GenericServer reference for full documentation of:
  • Resources: refresh(), resources(), getRAM(), getCPU(), getDisk(), getNetworkIn(), getNetworkOut(), getUptime()
  • Status: getStatus(), isOnline(), isOffline()
  • Power: powerAction(), start(), stop(), restart(), kill()
  • Files: listFiles(), downloadFile(), uploadFile(), deleteFiles(), renameFiles(), copyFiles(), moveFiles(), createFolder(), compress(), decompress()
  • Backups: listBackups(), createBackup(), deleteBackup(), downloadBackup()
  • Databases: listDatabases(), createDatabase(), rotateDatabasePassword(), deleteDatabase()
  • Startup: getStartupVariables(), updateStartupVariable()
  • Schedules: listSchedules(), createSchedule(), updateSchedule(), deleteSchedule(), runSchedule(), enableSchedule(), disableSchedule(), getSchedule()

Build docs developers (and LLMs) love

Get started for freeTalk to us