HyQuery

HyQuery

Let server lists show your server's status - players online, MOTD, and more!

What is HyQuery?

HyQuery is a server query protocol developed specifically for Hytale servers. Once installed, server lists and monitoring tools can automatically display your player count, server name, and other details - no manual updates needed!

Whether you're building a server listing website, a Discord bot, or a server management tool, HyQuery provides a standardized way to get server information.

HyQuery is the standard implementation for most Hytale server lists.

Why HyQuery?

Install and forget — works out of the box, no configuration required

Works on your existing port — no firewall changes needed for standalone setups

Set a custom MOTD — show something different on server lists

Privacy friendly — you control exactly what info is shared

Network support — aggregate player counts across multiple servers

What gets shared?

By default, just the basics:

Server name and MOTD

Player count (current and max)

Server version

Response latency

You can optionally enable:

List of online players

List of installed plugins

Response Format

HyQuery returns server information in a simple JSON format:

{ "online": true, "players": { "online": 42, "max": 100 }, "version": "1.0.0", "motd": { "raw": "Welcome to My Server!", "clean": "Welcome to My Server!" }, "latency": 24 }

Getting Started

Standalone Setup

For a single server, it's as simple as:

Download the plugin

Drop it in your mods folder

Restart your server

That's it!

Network Setup

If you're running a network with multiple servers (such as a lobby and several minigame servers), HyQuery supports aggregating player counts across your entire network. This allows server lists to display your total network population accurately.

Note: Our current build supports single-hub networks. Multi-hub support is coming soon.

How It Works

The network feature uses a primary/worker architecture. Your hub server acts as the primary and receives player count updates from all your worker servers (minigames, gamemodes, etc.). When queried, the primary aggregates all connected worker data into a single response.

1. Install on All Servers

Download HyQuery and place it in the mods folder on all servers in your network (hub and workers).

2. Configure Your Hub Server (Primary)

On your hub server, configure the plugin as the primary node:

{ "enabled": true, "showPlayerList": true, "showPlugins": false, "useCustomMotd": false, "customMotd": "My Network", "network": { "enabled": true, "role": "primary", "workerTimeoutSeconds": 30, "workers": [ { "id": "minigame-1", "key": "your-secret-key" }, { "id": "minigame-2", "key": "your-secret-key" } ] } } 3. Configure Your Worker Servers

On your minigame/gamemode servers, configure each as a worker:

{ "enabled": true, "showPlayerList": true, "showPlugins": false, "useCustomMotd": true, "customMotd": "Minigame Server", "network": { "enabled": true, "role": "worker", "id": "minigame-1", "primaryHost": "lobby.example.com", "primaryPort": 5520, "key": "your-secret-key", "updateIntervalSeconds": 5 } } 4. Open the Port

Make sure to open the HyQuery port (default: 5520) on your hub server so it can be queried externally and receive updates from workers.

Customisation

If you want to tweak things, edit mods/HyQuery/config.json:

Turn the query on or off

Show or hide player names

Show or hide plugins

Set a custom MOTD with colour codes

Configure rate limiting and caching

Enable network mode for multi-server setups

Tips

Debugging Network Mode

Set logStatusUpdates to true while configuring your network. This outputs to the console whenever updates are sent or received. Once everything is working, switch it back to false to reduce console spam.

Wildcard Support

You can use wildcards for worker IDs. Define minigame-* in your primary config, then configure individual servers as minigame-1, minigame-2, etc. with the same shared key. The primary will accept updates from all matching workers.

Test Your Setup

You can use the Server Status checker on Hyvote verify HyQuery is working correctly on your server.

Test Server Status →

Works With

Hyvote

Hytale Server

Hytale Servers

Hytale Rank

Running a server list? Get in touch on Discord to be added.

License

MIT - use it however you like!

Need a hand? 💬

Join us on Discord for setup help, bug reports, or just to chat with other server owners.

👉 https://discord.gg/7espErav5n