🌐 QueryHy - The Ultimate Hytale Server Monitoring Suite

QueryHy is a lightweight Hytale server plugin that exposes your server's live data through a built-in HTTP API — no external software required. Connect server lists, Discord bots, status pages, Grafana dashboards, or any custom tool in seconds.

Features at a Glance

Interactive Web Dashboard

A modern, dark-themed dashboard is available directly in your browser at http://your-server:5523/. No setup required — just open it.

• Real-time player list with session durations and UUIDs (click a player for details)
• RAM usage bar and configurable critical-usage alert
• Historical charts for player count and RAM (persisted across restarts)
• Live chat log

Remote Console

Execute server commands directly from the dashboard — secured behind your API key. Results appear instantly without leaving the page.

JSON API

Query your server's state from any application:

{
  "currentPlayers": 3,
  "maxPlayers": 100,
  "players": [
    { "name": "Steve", "uuid": "...", "sessionDurationSeconds": 42, "sessionDurationFormatted": "42s" }
  ],
  "uptimeFormatted": "1h 4m 12s",
  "serverName": "My Hytale Server",
  "peakPlayers": 12,
  "totalJoins": 84,
  "ramUsage": { "usedMb": 512, "totalMb": 1024, "maxMb": 2048 }
}

Prometheus / Grafana Support

The /metrics endpoint delivers data in standard Prometheus text format — ready to scrape with no additional configuration.

Security First

• API key is auto-generated on first launch using a cryptographically secure random generator
• Keys are accepted only via the X-API-Key header (never via URL parameters)
• Constant-time key comparison prevents timing-based attacks
• Full XSS protection: all player names and chat messages are escaped before rendering
• Per-IP rate limiting with a configurable token-bucket algorithm

Endpoints

Installation

1. Drop QueryHy.jar into your server's mods/ folder
2. Start the server — config.json and a secure API key are generated automatically
3. Note the API key from the server log or config.json
4. Open http://your-server:5523/ in your browser

Done. No port forwarding setup needed beyond opening port 5523 (configurable).

Configuration

All settings live in config.json inside the plugin's data directory. Every value is validated on load — invalid entries are automatically corrected to safe defaults.

{
  "port": 5523,
  "apiKey": "AUTO_GENERATED",
  "enableDashboard": true,
  "dashboardRefreshSeconds": 3,
  "ramWarningPercentage": 90.0,
  "enableRateLimit": true,
  "rateLimitRequestsPerSecond": 5.0,
  "rateLimitBurstCapacity": 10,
  "enableCors": true,
  "maxChatLogEntries": 50,
  "maxChartEntries": 240
}

Each data field in the /query response can be toggled individually (showMaxPlayers, showPlayerNames, showRamUsage, etc.) to expose only what you need.

Commands

Use Cases

• Server list websites — poll /query to display live player counts and server info
• Discord bots — show online players and uptime in a status channel
• Grafana dashboards — scrape /metrics and build professional monitoring boards
• Custom admin tools — use the REST API to automate server management
• Status pages — hit /health for a simple uptime indicator

Requirements

• Hytale Server
• Java 25+
• Port 5523 accessible (configurable)

Compatibility

QueryHy embeds its own HTTP server (com.sun.net.httpserver) — it has no external runtime dependencies and does not conflict with other plugins.

Developed by BSoftware - Empowering Hytale Server Admins.