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 via Redis
Anti-spoofing — V2 challenge-token handshake prevents UDP amplification attacks

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.

How It Works

The network feature uses a primary/worker architecture. Your hub server acts as the primary and your game servers act as workers. All servers connect to a shared Redis instance — workers publish their player data, and the primary aggregates it into a single response when queried. This supports hub clustering with multiple primary servers out of the box.

You'll need a Redis server accessible to all your game servers. This can run on the same machine as your primary, or on a dedicated host. Secure it with a strong password and make sure port 6379 is open between your servers.

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 that aggregates data from Redis:

{
  "enabled": true,
  "showPlayerList": true,
  "showPlugins": false,
  "network": {
    "enabled": true,
    "role": "primary",
    "coordinator": "redis",
    "namespace": "global",
    "staleAfterSeconds": 10,
    "redis": {
      "host": "127.0.0.1",
      "port": 6379,
      "password": "your-redis-password",
      "tls": false,
      "requireAvailable": true
    },
    "logStatusUpdates": false
  }
}

3. Configure Your Worker Servers

On your minigame/gamemode servers, configure each as a worker that publishes to the same Redis instance:

{
  "enabled": true,
  "network": {
    "enabled": true,
    "role": "worker",
    "coordinator": "redis",
    "id": "minigame-1",
    "namespace": "global",
    "redis": {
      "host": "127.0.0.1",
      "port": 6379,
      "password": "your-redis-password",
      "tls": false,
      "requireAvailable": true
    },
    "logStatusUpdates": false
  }
}

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
Enable or disable V1 and V2 protocols independently

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.

Namespaces

Use the namespace setting to isolate groups of servers within the same Redis instance. All servers sharing a namespace will be aggregated together. This is useful if you're running multiple networks on the same Redis server.

Test Your Setup

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

Test Server Status →

Works With

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