How to install HyQuery on your Hytale server - make your server visible on server lists

Why Your Hytale Server Needs HyQuery

When you run a Hytale server, players can only join if they already know your server address. Unlike older games like Counter-Strike or TF2, Hytale has no built-in server query protocol. There's simply no way for server browsers to automatically pick up your server's name, player count, or version.

HyQuery fixes that. It's a free, open-source plugin that adds a lightweight query protocol to your server. Once installed, server list websites like MantaScope can poll your server and show it to players looking for a game.

What HyQuery Does

• Makes your server discoverable - server browsers can see your server name, player count, max players, and version
• Zero extra ports - works on the same UDP port your server already uses (default 5520), so no extra firewall rules or port forwarding needed
• Privacy by default - player names are hidden unless you explicitly turn on the player list
• Lightweight - uses a binary protocol that adds almost no overhead to your server
• Secure - built-in rate limiting protects against UDP amplification attacks

What Happens Without It

Without HyQuery, your server is invisible to server browsers. Players can still connect by typing your IP address manually, but you're missing out on most players who browse server lists to find new servers.

---

Installation (2 Minutes)

Step 1: Download the Plugin

Go to the HyQuery releases page on GitHub and download the latest .jar file. As of writing, the latest version is v2.0.0.

Look for the file named something like hyquery-plugin-2.0.0.jar under the Assets section of the latest release.

Step 2: Place It in Your Mods Folder

Copy the downloaded .jar file into your Hytale server's mods/ directory:

your-hytale-server/
├── mods/
│   └── hyquery-plugin-2.0.0.jar   ← put it here
├── server.jar
└── ...

If you're on a hosting provider like Nitrado, GGServers, or Apex Hosting, look for a "Mods" or "Plugins" section in your control panel and upload the file there.

Step 3: Start (or Restart) Your Server

Start your server normally. HyQuery will automatically:

1. Detect your server's game port
2. Start listening for query requests on that same port
3. Generate a config file at mods/HyQuery/config.json

That's it, your server is now queryable.

Step 4: Verify It Works

Add your server to MantaScope at mantascope.com/submit-server. Select Hytale as the game, enter your server address and port (default 5520), and submit. Within a few minutes your server should show up in the Hytale server list with its name, player count, and version.

---

Configuration

After the first start, you'll find a config file at mods/HyQuery/config.json. Here are the important settings:

Basic Settings

{
  "enabled": true,
  "showPlayerList": false,
  "showPlugins": false,
  "useCustomMotd": false,
  "customMotd": "Welcome to my server!"
}

Security Settings

{
  "rateLimitEnabled": true,
  "rateLimitPerSecond": 10,
  "rateLimitBurst": 20,
  "cacheEnabled": true,
  "cacheTtlSeconds": 5
}

The defaults work well for most servers. Rate limiting prevents abuse, and caching cuts CPU usage when multiple server browsers query you at once.

Restart your server after changing any settings.

---

For Server Networks (Multiple Servers)

If you run multiple connected Hytale servers (like a lobby + game servers), HyQuery v1.2+ supports a primary/worker setup:

• Primary server: The one listed on server browsers. It collects player counts from all workers.
• Worker servers: Report their status to the primary over authenticated UDP.

This way the server list shows your total player count across all servers, not just one.

To set this up, mark one server as networkPrimary: true and point the others to the primary's address. Check the HyQuery GitHub for the full network configuration.

---

Version History

---

Troubleshooting

Server not showing up on MantaScope?

• Make sure the .jar file is in the mods/ folder (not a subfolder)
• Check that enabled is true in your config
• Verify your firewall allows UDP traffic on port 5520 (or whatever port your server uses)
• Give it a few minutes, MantaScope polls servers every 5 minutes

Config file not appearing?

• The config is generated on first start. If it doesn't show up, check your server logs for errors related to HyQuery.

"Hytale Server" showing as name instead of your custom name?

• HyQuery reads the server name from your Hytale server configuration, not from the HyQuery config. Set your server name in your main Hytale server settings.
• Or enable useCustomMotd and set customMotd to override the displayed description.

---

Links

• HyQuery on GitHub - source code and docs
• Download Latest Release - get the plugin
• Add Your Server to MantaScope - submit your server
• Browse Hytale Servers - see all tracked Hytale servers