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.

BridgeClient is a thin Python client for the HungerBridge v2 REST API. It handles authentication via the X-Auth-Key header and raises typed exceptions (HungerBridgeError, InvalidLevelError, InvalidModeError) on error conditions. Every MinecraftServer instance creates and owns a BridgeClient at self.bridge; you can also instantiate one directly for standalone bridge access. 
from hungerlib.bridgeclient import BridgeClient

client = BridgeClient("http://mc.example.com:8080", "my-secret-token")

print(client.getPing())           # e.g. 4  (ms)
print(client.getTPS())            # e.g. 19.98
print(client.getPlayers("list"))  # ["Steve", "Alex"]

​
Constructor

BridgeClient(url: str, token: str)
​
url
str
required
Base URL of the HungerBridge instance, e.g. "http://mc.example.com:8080". Trailing slashes are stripped and /v2/ is appended automatically.
​
token
str
required
The X-Auth-Key authentication token configured in HungerBridge.

​
Raw Endpoints

These methods call the HungerBridge v2 REST endpoints directly and return the raw parsed JSON response as a dict. Use them when you need fields not exposed by the higher-level getters. All raw endpoint methods raise HungerBridgeError if the HTTP response is not successful.

​
v2_ping()

client.v2_ping() -> dict
Calls GET /v2/ping. Used internally by getPing() to measure round-trip latency. Returns dict — bridge ping response.

​
v2_info()

client.v2_info() -> dict
Calls GET /v2/info. Returns version and platform metadata about the running bridge instance. Returns dict containing a "bridge" object with "version", "platform", and "minecraft" keys.

​
v2_status()

client.v2_status() -> dict
Calls GET /v2/status. Returns a simple health/connection status. Returns dict with an "ok" boolean field.

​
v2_tps()

client.v2_tps() -> dict
Calls GET /v2/tps. Returns all TPS metrics from the server. Returns dict with keys "tps", "tps_1m", "tps_5m", and "tick_time_ms".

​
v2_players()

client.v2_players() -> dict
Calls GET /v2/players. Returns online player data. Returns dict with keys "count" (int) and "players" (list of str).

​
Public API

​
runCommand()

client.runCommand(
    command: str,
    show_console: bool = False,
    silent: bool = False,
    normalize: bool = True,
) -> str | dict | None
Executes a command on the Minecraft server via POST /v2/run and returns the output.
​
command
str
required
The server command to execute, without a leading /, e.g. "op Steve" or "whitelist add Alex".
​
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, the command runs without generating in-game feedback messages.
​
normalize
bool
default:"True"
When True (default), output is returned as a single str with lines joined by \n. When False, the raw bridge response (dict or str) is returned as-is.
Returns str of normalised output when normalize=True, or the raw response object when normalize=False. Returns None if the bridge returns no output field. Raises HungerBridgeError if the HTTP request fails. 
out = client.runCommand("list", show_console=True)
# "There are 2 of a max of 20 players online: Steve, Alex"

​
log()

client.log(message: str, level: str = "info") -> dict
Sends a log message to the server console via POST /v2/log.
​
message
str
required
The message text to log.
​
level
str
default:"info"
Log severity level. Must be one of "info", "warn", "error", or None. Passing None strips the log level prefix from the output using a backspace sequence, producing unformatted console output.
Returns dict — the bridge’s response body. Raises InvalidLevelError if level is not one of the four accepted values. 
client.log("Backup started", level="info")
client.log("Low disk space", level="warn")
client.log("Crash detected", level="error")

​
Getters

​
getPing()

client.getPing() -> int
Measures the round-trip latency to the bridge by timing a v2_ping() call client-side. Returns int — round-trip time in milliseconds. Raises HungerBridgeError if the bridge is unreachable.

​
getVersion()

client.getVersion() -> str | None
Returns str — the HungerBridge plugin version string (e.g. "2.1.0"), or None if not present in the response. Raises HungerBridgeError if the HTTP request fails.

​
getPlatform()

client.getPlatform() -> str | None
Returns str — the server software platform (e.g. "Paper", "Spigot"), or None if not present. Raises HungerBridgeError if the HTTP request fails.

​
getMinecraftVersion()

client.getMinecraftVersion() -> str | None
Returns str — the Minecraft version string (e.g. "1.21.1"), or None if not present. Raises HungerBridgeError if the HTTP request fails.

​
getStatus()

client.getStatus() -> bool
Returns bool — the value of the "ok" field from v2_status(). True indicates the bridge is healthy and connected to the server. Raises HungerBridgeError if the HTTP request fails.

​
getTPS()

client.getTPS(mode: str = "current") -> float
Returns one of four TPS measurements from the v2_tps() endpoint.
​
mode
str
default:"current"
Selects which metric to return:
ModeFieldDescription
"current"tpsEMA20 — exponential moving average over the last 20 ticks. Reflects near-real-time server performance.
"1m"tps_1mEMA1200 — smoothed average over approximately the last 1 minute of ticks.
"5m"tps_5mEMA6000 — smoothed average over approximately the last 5 minutes of ticks.
"tick_time"tick_time_msAverage tick duration in milliseconds. A healthy server targets ≤ 50 ms per tick.
Returns float — the requested TPS value. Raises InvalidModeError if mode is not one of the four accepted values. Raises HungerBridgeError if the HTTP request fails. 
client.getTPS()             # 19.98   (EMA20)
client.getTPS("1m")         # 19.75   (1-minute EMA)
client.getTPS("5m")         # 19.50   (5-minute EMA)
client.getTPS("tick_time")  # 1.24    (ms per tick)

​
getPlayers()

client.getPlayers(mode: str = "count") -> int | list
​
mode
str
default:"count"
Selects what to return:
  • "count" — returns the integer number of currently online players.
  • "list" — returns a list[str] of online player usernames.
Returns int when mode="count", list[str] when mode="list". Raises InvalidModeError if mode is not "count" or "list". Raises HungerBridgeError if the HTTP request fails. 
client.getPlayers()          # 5
client.getPlayers("list")    # ["Steve", "Alex", "Notch", "Herobrine", "Dream"]

​
Exceptions

​
HungerBridgeError
Exception
Raised by any method when the HungerBridge HTTP response has a non-2xx status code, or when a response cannot be parsed. Inherits from the base Exception class directly (not HungerLibError).
​
InvalidLevelError
HungerLibError
Raised by log() when the supplied level argument is not "info", "warn", "error", or None.
​
InvalidModeError
HungerLibError
Raised by getTPS() and getPlayers() when the mode argument is not a recognised value.

Build docs developers (and LLMs) love

Get started for freeTalk to us