Hytale Query Plugin: Monitor your server status

For any Hytale server administrator, having reliable, real-time information about their server’s status is fundamental. Whether it’s for populating a dashboard, monitoring activity, or integrating external services, access to server data is essential. This is precisely the role of the Hytale Query plugin.

This plugin exposes structured information about your server, from the number of connected players to a list of installed plugins, via a simple HTTP access point. It’s a powerful, secure, and essential tool for professional server management.

Prerequisite: the WebServer plugin

First and foremost, it is crucial to understand that this plugin has a major dependency: the  Hytale WebServer plugin . The Query plugin relies on the latter to create and manage the HTTP access point.

Therefore, make sure you have correctly installed and configured the WebServer plugin before proceeding with the installation of the Query plugin.

Installing the plugin

Installing the Query plugin is a simple process that only takes a few moments.

1. Download the latest version of the Hytale Query plugin JAR file from its official development project.
2. Copy this file  directly into  your Hytale server .jar folder  .mods/
3. Restart your server.

The plugin will be automatically loaded and activated, ready to respond to requests.

Usage and access point

Once installed, the plugin is immediately functional. It only registers a single access point (or  endpoint ) to retrieve all the information.

The access point (Endpoint)

To query your server, simply send a request  GET to the following URL:
/Nitrado/Query

This request, made to the IP address and port of your web server configured via the WebServer plugin, will return a response in JSON format containing server information.

Example JSON response

Here is an example of the data structure you might receive. Note that the actual content will depend on the permissions granted to the user making the request.

{
  "Server": {
    "Name": "Mon Super Serveur Hytale",
    "Version": "2026.01.10-ab2cd69ff",
    "MaxPlayers": 100
  },
  "Universe": {
    "CurrentPlayers": 15,
    "DefaultWorld": "monde_principal"
  },
  "Players": [
    {
      "Name": "JoueurExemple",
      "UUID": "e5c4ef9a-6281-406e-8a71-21028279f547",
      "World": "monde_principal"
    }
  ],
  "Plugins": {
    "Nitrado:WebServer": {
      "Version": "1.0.0",
      "Enabled": true,
      "State": "ENABLED"
    },
    "Nitrado:Query": {
      "Version": "1.0.0",
      "Enabled": true,
      "State": "ENABLED"
    }
  }
}

Permissions management

The true power of this plugin lies in its seamless integration with Hytale’s permissions system. By default, no information is exposed. You must explicitly grant permissions for data to be visible. This ensures that only authorized users can access sensitive information.

The JSON response is dynamically filtered based on the permissions of the user (or group) making the request. If a user only has permission to view universe information, only that section  "Universe" will appear in the response.

Key permissions

The plugin defines four distinct permissions, each controlling access to a specific section of the data.

Permission	Corresponding data section
nitrado.query.web.read.server	Server information ( Server)
nitrado.query.web.read.universe	Information about the universe ( Universe)
nitrado.query.web.read.players	List of connected players ( Players)
nitrado.query.web.read.plugins	List of installed plugins ( Plugins)

How can certain information be made public?

A very common use is to publicly display the server name and the number of connected players, for example, on a website. To do this, simply assign the corresponding permissions to the group  ANONYMOUS in your file  permissions.json.

This special group is used for all requests made without authentication.

Example configuration in  permissions.json :

{
  "Groups": {
    "ANONYMOUS": [
      "nitrado.query.web.read.server",
      "nitrado.query.web.read.universe"
    ]
  }
}

With this configuration, anyone querying the endpoint  /Nitrado/Query will only receive the sections  Server and  Universe, without needing to authenticate.