HyQuery

What is HyQuery?

HyQuery is a server query protocol developed by the Hyvote team specifically for Hytale servers. It allows external applications, websites, and tools to retrieve real-time information about a Hytale server.

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 including online status, player count, MOTD (Message of the Day), server version, and response latency.

HyQuery is the standard implementation for most Hytale server lists.

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
}

Installation (Standalone Server)

For a single server setup, follow these steps:

1. Download the Plugin

Download the latest HyQuery release and place it in your server's mods folder.

GitHub Releases CurseForge

2. Configure the Plugin

After first run, a configuration file will be created at mods/HyQuery/config.json. HyQuery uses the same port as your game server (default 5520), so no additional port configuration is needed.

{
  "enabled": true,
  "showPlayerList": false,
  "showPlugins": false,
  "useCustomMotd": false,
  "customMotd": "",
  "rateLimitEnabled": true,
  "rateLimitPerSecond": 10,
  "rateLimitBurst": 20,
  "cacheEnabled": true,
  "cacheTtlSeconds": 5,
  "v1Enabled": true,
  "v2Enabled": true
}

3. Test Your Setup

Use our Server Status tool to verify HyQuery is working correctly on your server.

Installation (Network)

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.

Servers in your network publish their state to a shared Redis instance. Your hub server reads from Redis and aggregates the data into a single response. This supports hub clustering with multiple primary servers out of the box.

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.

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. Download the Plugin

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

GitHub Releases CurseForge

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
  }
}

4. Test Your Setup

Use our Server Status tool to verify HyQuery is working correctly on your hub server.

Tips

Debugging

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.

Frequently Asked Questions

Do I need HyQuery for Hyvote?

You don't need to use HyQuery for Hyvote, but it is the recommended method. You can also use Nitrado Query, which exposes information from a webserver running on the server. You can also not configure polling at all, but servers that have live player counts tend to receive more joins from potential players.

Is HyQuery open source?

Yes! HyQuery is fully open source and available on GitHub. You can view the source code, contribute, or fork it for your own projects.

What if my server shows offline?

Make sure the HyQuery port is open in your firewall, the plugin is installed and running, and you've selected the correct query method when adding your server to Hyvote.

What is the difference between V1 and V2?

V2 adds a challenge-token handshake to prevent UDP amplification attacks, uses new protocol magic bytes (HYQUERY2/HYREPLY2), and uses Redis for network coordination. V1 remains available for backwards compatibility but we recommend migrating to V2.