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. The default port is 5520 but you can change it in the config. This should be the same as your game port.

# config.yml
port: 5520
enable_motd: true
enable_player_list: false

3. Open the Port

Make sure to open the HyQuery port (default: 5520) in your firewall and server hosting panel. This port must be accessible for external queries.

4. 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.

Note: Our current preview build supports single-hub networks. Multi-hub support is coming soon in a future release.

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. 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 will receive updates from workers:

{
  "enabled": true,
  "showPlayerList": true,
  "showPlugins": false,
  "useCustomMotd": false,
  "customMotd": "Hyfable",
  "rateLimitEnabled": true,
  "rateLimitPerSecond": 10,
  "rateLimitBurst": 20,
  "cacheEnabled": true,
  "cacheTtlSeconds": 5,
  "network": {
    "enabled": true,
    "role": "primary",
    "workerTimeoutSeconds": 30,
    "workers": [
      { "id": "us-main", "key": "your-secret-key" },
      { "id": "eu-main", "key": "your-secret-key" },
      { "id": "minigame-1", "key": "minigame-secret-key" },
      { "id": "minigame-2", "key": "minigame-secret-key" }
    ],
    "id": "",
    "primaryHost": "",
    "primaryPort": 5520,
    "key": "",
    "updateIntervalSeconds": 5,
    "logStatusUpdates": false
  }
}

3. Configure Your Worker Servers

On your minigame/gamemode servers, configure each as a worker that reports to the primary:

{
  "enabled": true,
  "showPlayerList": true,
  "showPlugins": false,
  "useCustomMotd": true,
  "customMotd": "Minigame Server",
  "rateLimitEnabled": true,
  "rateLimitPerSecond": 10,
  "rateLimitBurst": 20,
  "cacheEnabled": true,
  "cacheTtlSeconds": 5,
  "network": {
    "enabled": true,
    "role": "worker",
    "workerTimeoutSeconds": 30,
    "workers": [],
    "id": "minigame-1",
    "primaryHost": "lobby.example.com",
    "primaryPort": 5520,
    "key": "minigame-secret-key",
    "updateIntervalSeconds": 5,
    "logStatusUpdates": false
  }
}

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.

5. 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.

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.

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.