HGS Query Plugin

Official Hytale server plugin for HytaleGameServers.net — the premier server listing platform for Hytale.

This plugin keeps your server listing on HytaleGameServers.net up to date by periodically sending server status, player counts, and other metadata to the API.

✨ Features

🔄 Automatic Status Updates — Real-time player counts, MOTD, world info, and more sent to your server listing
🌐 Network Mode — Run multiple Hytale servers as a single listing with automatic controller election and peer-to-peer TCP communication
⚡ Fully Asynchronous — All API calls and network I/O run on asynchronous threads with zero impact on gameplay
🔒 Secure Communication — HTTPS with Bearer token authentication
🛡️ Privacy Controls — Toggle what data is shared: player usernames, system environment, installed plugins
📊 Dynamic Intervals — 3 minute updates by default (1 minute for sponsored/real-time servers) — faster than the website's built-in Query Port polling

📦 Installation

Download the plugin
Place the .jar file into your server’s mods/ folder
Start your server to generate config files
Create a server listing on HytaleGameServers.net
Go to your Dashboard and click "Api"
Add your Server ID and API Token to Api.json
Restart your server — done!

⚙️ Configuration

`Api.json`

Your server credentials. Obtain these from your server dashboard on HytaleGameServers.net.

{
  "serverId": "YOUR_SERVER_ID_HERE",
  "apiToken": "YOUR_API_TOKEN_HERE"
}

🔑 Keep your API token private. Do not share it publicly or commit it to version control.

`Config.json`

General plugin settings and privacy controls.

Setting	Default	Description
`enabled`	`true`	Master toggle — set to `false` to disable all API communication
`sendSystemEnvironmentName`	`true`	Include OS name (e.g. "Windows 10", "Linux") in updates
`sendOnlinePlayerUsernames`	`true`	Include individual player usernames (player counts are always sent)
`sendPluginInfo`	`true`	Include installed plugin list (group, name and version only)

`Network.json` (Multi-Server Only)

Required only if you're running multiple Hytale servers as a single listing.

Setting	Default	Description
`enabled`	`false`	Enable network mode
`nodeId`	`"DEFAULT"`	Unique identifier for this node (e.g. `LOBBY`, `SURVIVAL-1`, `FACTIONS`)
`port`	`9800`	TCP port for inter-node communication
`nodes`	`[]`	List of peer addresses in `"host:port"` format (do not include this node)

How network mode works:

Each node runs a TCP server and connects to all configured peers. Heartbeats track liveness every 5 seconds. The node with the lowest nodeId (lexicographic) is automatically elected as the controller. The controller collects snapshots from all peers and sends a single aggregated update to the HGS API.

If the controller goes down, a new controller is elected automatically — no manual intervention required.

Example — 3 server network:

On LOBBY (port 9800):

{
  "enabled": true,
  "nodeId": "LOBBY",
  "port": 9800,
  "nodes": ["192.168.1.11:9800", "192.168.1.12:9800"]
}

On SURVIVAL (192.168.1.11):

{
  "enabled": true,
  "nodeId": "SURVIVAL",
  "port": 9800,
  "nodes": ["192.168.1.10:9800", "192.168.1.12:9800"]
}

On FACTIONS (192.168.1.12):

{
  "enabled": true,
  "nodeId": "FACTIONS",
  "port": 9800,
  "nodes": ["192.168.1.10:9800", "192.168.1.11:9800"]
}

⚠️ All nodes must share the same serverId and apiToken in their Api.json.

📋 Data Collected

The plugin sends the following to HytaleGameServers.net:

Server name, MOTD, address, and port
Current and maximum player count
Online player usernames and UUIDs (if enabled)
World names and count
Server implementation version
Installed plugins — group, name, and version only (if enabled)
System environment name (if enabled)
Password protection status (boolean only — no passwords are ever transmitted)
Server boot timestamp

All data is automatically cleared when your server goes offline.

🔗 API Endpoints

The plugin communicates exclusively with:

POST https://hytalegameservers.net/api/plugin/query/update — Status updates
POST https://hytalegameservers.net/api/plugin/query/shutdown — Graceful shutdown notification

⏱️ Update Intervals

There are two ways your server listing stays up to date — the plugin (this project) and the website's built-in Query Port polling. The plugin is faster and takes priority.

Method	Default Interval	Sponsored / Real-Time
Plugin (recommended)	3 minutes	1 minute
Query Port (website-side)	5 minutes	1 minute

When the plugin is actively syncing with the API, the website backend will not query your server's Query Port — the plugin takes over entirely. Query Port polling only applies to servers that don't have this plugin installed.

📝 Requirements

Hytale Server (official release)
Java 21+
Account and server listing on HytaleGameServers.net
Outbound HTTPS access to hytalegameservers.net

🔨 Building from Source

git clone https://github.com/HytaleGameServers/Query-Plugin.git
cd Query-Plugin
mvn clean package

The compiled JAR will be in the target/ directory.

💬 Support

🌐 Website: hytalegameservers.net
💬 Discord: hytalegameservers.net/discord

⚠️ Important Notice

Abuse of the API or plugin is strictly prohibited. This includes attempting to bypass rate limits, sending falsified data, reverse engineering for malicious purposes, or any other violation of our Terms of Service. Violations will result in suspension or permanent termination of your server listing and account.

This is an unofficial community project. Hytale is a trademark of Hypixel Studios.

HGS-Query