How to Install HyQuery on Your Hytale Server: Complete Setup Guide

By Admin43 views

Get your Hytale server discovered by more players with real-time stats and live player counts on server listing sites.

What is HyQuery?

HyQuery is a lightweight query plugin for Hytale servers that enables server listing websites to display real-time information about your server. When installed, HyQuery broadcasts live data including your current player count, maximum player slots, server status, and other metadata that helps players find and choose your server.

Without a query plugin like HyQuery, server listing sites can only display static information you've manually entered. With HyQuery, your listing becomes dynamic — showing players exactly what's happening on your server right now.

Why HyQuery Helps Your Server Get More Players

Live Server Stats Build Trust

Players are far more likely to join servers that display real-time information. When a potential player sees "24/50 players online" updated live, they know your server is active and legitimate. Static listings without live data often get skipped over because players can't verify the server is actually running.

Higher Rankings on Server Lists

Server listing sites like HytaleWorld.gg use live data as a ranking factor. Servers with verified, real-time stats rank higher in search results because they provide a better experience for players. By installing HyQuery, you're signaling to listing sites that your server is trustworthy and well-maintained.

Accurate Player Counts Drive Engagement

Nothing attracts players like seeing other players. When your server shows 30 people online, it creates social proof that encourages others to join. HyQuery ensures your player count is always accurate, so players know exactly what to expect before they connect.

Stand Out From Unverified Servers

Many server owners skip query plugin setup. By taking the extra step to install HyQuery, your server displays a "verified" badge on supported listing sites, immediately distinguishing you from servers that haven't completed this setup.

Requirements Before You Start

Before installing HyQuery, make sure you have:

  • A running Hytale server with administrative access

  • Access to your server's file system (via FTP, SFTP, or direct access)

  • The ability to modify server configuration files

Step-by-Step HyQuery Installation Guide

Step 1: Download the HyQuery Plugin

Download the latest version of HyQuery from the official repository. Always use the official source to ensure you're getting a secure, up-to-date version of the plugin.

https://github.com/Hyvote/hyquery

Download the .jar file (or appropriate plugin format for your server software) to your local computer.

Step 2: Upload HyQuery to Your Server

Connect to your Hytale server using your preferred file transfer method:

Using SFTP/FTP:

  1. Connect to your server using an FTP client like FileZilla

  2. Navigate to your server's plugins folder

  3. Upload the HyQuery plugin file to this directory

Using a Server Panel (Nitrado, etc.):

  1. Log into your server control panel

  2. Navigate to File Manager or File Browser

  3. Open the plugins directory

  4. Upload the HyQuery plugin file

Step 3: Configure the Query Port

HyQuery needs a dedicated port to respond to queries from server listing sites. Open your server's main configuration file and ensure query settings are enabled.

Add or modify these settings in your server configuration:

query:
  enabled: true
  port: 5520

The default query port is 5520, but you can use any available port. We recommend using 5520 to work optimally with HytaleWorld configuration.

Step 4: Open the Query Port on Your Firewall

For server listing sites to reach your HyQuery plugin, the query port must be accessible from the internet.

For Linux servers:

sudo ufw allow 5520/udp

For Windows servers:

  1. Open Windows Firewall with Advanced Security

  2. Create a new Inbound Rule

  3. Select "Port" and click Next

  4. Select "UDP" and enter your query port (5520)

  5. Allow the connection and complete the wizard

For hosted servers (Nitrado, etc.): Most hosting providers automatically open standard query ports. Check your provider's documentation or contact support if queries aren't working.

Step 5: Restart Your Server

After uploading the plugin and configuring the port, restart your Hytale server to load HyQuery:

# Stop your server gracefully
stop

# Start the server again
./start.sh

Or use your control panel's restart button if you're using a hosting provider.

Step 6: Verify HyQuery is Working

Once your server restarts, check the console output for a message confirming HyQuery has loaded successfully. You should see something like:

[HyQuery] Plugin enabled successfully
[HyQuery] Listening for queries on port 5520

Testing Your HyQuery Setup

Before submitting your server to listing sites, verify that HyQuery is responding to external queries.

Use an Online Query Tool

Visit a Hytale server query testing tool and enter your server's IP address and query port. If configured correctly, you should see your server's live information returned.

Check From Your Listing Dashboard

After adding your server to HytaleWorld.gg or another listing site, check your server's dashboard. Look for a "verified" status or green indicator showing that live stats are being received.

Troubleshooting Common HyQuery Issues

Query Port Not Responding

If your query port isn't responding to external requests:

  1. Check firewall settings — Ensure UDP traffic is allowed on your query port

  2. Verify the port number — Make sure the port in your config matches what you've opened

  3. Check for port conflicts — Another service might be using the same port

  4. Contact your host — Some providers block non-standard ports by default

Plugin Not Loading

If HyQuery doesn't appear in your plugin list:

  1. Check the server version — Ensure HyQuery is compatible with your server software version

  2. Review console errors — Look for error messages when the server starts

  3. Verify file permissions — The plugin file needs read permissions

Stats Not Updating on Listing Sites

If your server shows as "online" but stats seem stale:

  1. Check query frequency — Listing sites typically query every 1-5 minutes

  2. Verify all data fields — Some stats require additional configuration

  3. Clear listing cache — Some sites cache data; try refreshing your listing

Maximizing Your Server's Visibility

Installing HyQuery is just the first step. Here's how to get the most out of your live server stats:

Keep Your Server Online

Listing sites track uptime. Servers with consistent availability rank higher than those that frequently go offline. Consider using a reliable hosting provider or ensuring your self-hosted server has stable power and internet.

Optimize Your Server Description

Combine your live stats with a compelling server description. Tell players what makes your server unique — your game modes, community events, or custom content.

Encourage Player Reviews

Active servers with positive reviews rank higher. Encourage your players to leave reviews on server listing sites after they've had a good experience.

Update Your Listing Regularly

Keep your server listing's description, tags, and images current. Listing sites favor servers that maintain their profiles.

Frequently Asked Questions

Does HyQuery affect server performance?

No. HyQuery is extremely lightweight and only responds to incoming query requests. It doesn't continuously use CPU or memory resources.

Is HyQuery required for server listings?

While not strictly required, servers without query plugins display as "unverified" and rank lower than those with live stats enabled.

Can I use HyQuery with other plugins?

Yes. HyQuery is designed to work alongside other server plugins without conflicts.

What data does HyQuery share?

HyQuery shares publicly visible server information: player count, max players, server name, and online status. It does not share private player data, IP addresses, or sensitive server information.

Is HyQuery free to use?

Yes. HyQuery is free and open-source software.

Ready to Get More Players?

With HyQuery installed, your Hytale server is now ready to be discovered by more players. Your live stats will help you rank higher on server listing sites and build trust with potential players before they even connect.

Next step: Add your server to HytaleWorld.gg and start attracting players today.

Last updated: January 2026