How To Add Your Server To Hyvote with HyQuery

To list your Hytale server on Hyvote, your server must expose a public query endpoint so we can verify its status, player count, and basic metadata. This guide will show you how to set up HyQuery, a lightweight UDP query protocol designed for simplicity and speed.

While HyQuery is not the official method recommended by Hytale (that would be Nitrado Query), it offers several advantages that make it an excellent choice for many server operators.

Why Choose HyQuery?

HyQuery provides several key benefits over the official Nitrado Query method:

Benefit	Description
Single Plugin	Only one plugin required instead of two (WebServer + Query)
No Extra Ports	Uses your existing game server port (5520) - no additional port configuration needed
Custom MOTD	Set a custom MOTD with Minecraft color codes specifically for server lists
Shared Hosting Friendly	Perfect if your host won't provide additional TCP ports

This tutorial will walk you through the complete setup process. By the end, you will have successfully listed your server on Hyvote!

1. Install the HyQuery Plugin

You only need to install one plugin:

Plugin Name	Description	GitHub Repository
HyQuery	UDP query protocol for Hytale servers	hyvote/hyquery

To install the plugin:

1. Visit the HyQuery releases page
2. Download the latest hyquery-plugin-x.x.x-SNAPSHOT.jar file
3. Place the JAR file in your server's /mods folder
4. Restart your server

After the server starts, you should see HyQuery initialization messages in your server console:

[INFO] HyQuery loading...
[INFO] Loading configuration...
[INFO] Created default configuration at mods/Hyvote_HyQuery/config.json
[INFO] HyQuery starting...
[INFO] HyQuery enabled on UDP port 5520 (3 channels)

If you see these messages, the plugin has been installed successfully!

2. Configure HyQuery (Optional)

After the first startup, HyQuery automatically creates a configuration file at:

mods/Hyvote_HyQuery/config.json

The default configuration looks like this:

{
  "enabled": true,
  "showPlayerList": false,
  "showPlugins": false,
  "useCustomMotd": false,
  "customMotd": "§aWelcome to §lMy Server§r!"
}

Configuration Options

Option	Default	Description
enabled	true	Enable or disable the query server
showPlayerList	false	Include online player names and UUIDs in responses
showPlugins	false	Include installed plugin list in responses
useCustomMotd	false	Use custom MOTD instead of server config MOTD
customMotd	"§aWelcome..."	Custom MOTD with Minecraft color code support

The default configuration works out of the box. You only need to modify it if you want to:

• Show player names in server lists (set showPlayerList to true)
• Show your installed plugins (set showPlugins to true)
• Set a custom MOTD with color codes (set useCustomMotd to true)

Setting a Custom MOTD (Optional)

One of HyQuery's unique features is the ability to set a custom MOTD specifically for server lists, complete with Minecraft color codes. This MOTD is separate from your in-game MOTD and only appears on server lists like Hyvote.

To enable a custom MOTD, edit your config file:

{
  "enabled": true,
  "showPlayerList": false,
  "showPlugins": false,
  "useCustomMotd": true,
  "customMotd": "§6Welcome to §l§bMy Epic Server§r§6! §aJoin now!"
}

Minecraft Color Codes Reference

Code	Color/Format	Code	Color/Format
§0	Black	§8	Dark Gray
§1	Dark Blue	§9	Blue
§2	Dark Green	§a	Green
§3	Dark Aqua	§b	Aqua
§4	Dark Red	§c	Red
§5	Dark Purple	§d	Light Purple
§6	Gold	§e	Yellow
§7	Gray	§f	White
§l	Bold	§o	Italic
§m	Strikethrough	§n	Underline
§r	Reset (removes all formatting)

After making any configuration changes, restart your server for them to take effect.

3. Network & Port Configuration

One of HyQuery's biggest advantages is that it uses your existing game server port. There's no need to open additional ports or configure firewalls beyond what you've already done for your game server.

Port Information

Purpose	Default Port	Protocol	Notes
Game Server + HyQuery	5520	UDP	Both run on the same port seamlessly

How Does It Work?

HyQuery uses a clever technique to share the game server port. It intercepts UDP packets before the game's QUIC protocol processes them. By checking for special "magic bytes" (HYQUERY\0) at the start of each packet, HyQuery can identify and respond to query requests while passing all other traffic to the game server.

This means:

• No additional ports needed
• No firewall configuration required (beyond what your game server needs)
• Perfect for shared hosting where you can't get extra ports
• No conflicts with game server traffic

4. Test Your HyQuery Installation

Before adding your server to Hyvote, it's a good idea to test that HyQuery is responding correctly. You can use our Server Status Checker tool to verify your server is accessible.

1. Visit https://hyvote.org/tools/server-status
2. Enter your server IP address
3. Enter port 5520 (or your custom game server port)
4. Select HyQuery as the query method
5. Click Check Status

If your server is configured correctly, you'll see your server name, MOTD, player count, and version information. If the check fails, review the troubleshooting section below.

5. Add Your Server to Hyvote

Now that HyQuery is installed and tested, you're ready to list your server on Hyvote!

1. Log in to Hyvote with your Discord account
2. Navigate to your profile
3. Click "Add Server"
4. Fill in your server information - the more details you provide, the more appealing your server will be!

Query Configuration

When setting up the query configuration:

Field	Value
Query Method	Select HyQuery
Query Port	5520 (or your custom game server port)

Press Add Server and you're done! Hyvote will query your server within 15 to verify it's online and retrieve your server information.