Hytale Query Plugin: Monitor Your Server Status

For any Hytale server administrator, having reliable, real-time information about their server status is fundamental. Whether powering a dashboard, monitoring activity, or integrating external services, access to server data is a necessity. This is exactly the role of the Hytale Query plugin.

This plugin exposes structured information about your server—ranging from the number of connected players to the list of installed plugins—via a simple HTTP endpoint. It is a powerful, secure, and indispensable tool for professional server management.

Prerequisite: The WebServer Plugin

Before anything else, it is crucial to understand that this plugin has a major dependency: the Hytale WebServer plugin.

The Query plugin relies on the WebServer plugin to create and manage the HTTP endpoint. Therefore, ensure you have installed and correctly configured the WebServer plugin before proceeding with the installation of the Query plugin.

Plugin Installation

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

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

The plugin will automatically load and activate, ready to answer requests.

Usage and Endpoint

Once installed, the plugin is immediately functional. It registers a single endpoint to retrieve all information.

The Endpoint

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

/Nitrado/Query

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

JSON Response Example

Below 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": "My Super Hytale Server",
    "Version": "2026.01.10-ab2cd69ff",
    "MaxPlayers": 100
  },
  "Universe": {
    "CurrentPlayers": 15,
    "DefaultWorld": "main_world"
  },
  "Players": [
    {
      "Name": "ExamplePlayer",
      "UUID": "e5c4ef9a-6281-406e-8a71-21028279f547",
      "World": "main_world"
    }
  ],
  "Plugins": {
    "Nitrado:WebServer": {
      "Version": "1.0.0",
      "Enabled": true,
      "State": "ENABLED"
    },
    "Nitrado:Query": {
      "Version": "1.0.0",
      "Enabled": true,
      "State": "ENABLED"
    }
  }
}

Permissions Management

The real power of this plugin lies in its fine-grained integration with Hytale’s permission system.

By default, no information is exposed. You must explicitly grant permissions for data to be visible. This ensures that only authorized persons can access sensitive information.

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

Key Permissions

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

How to Make Certain Information Public?

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

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

Configuration example in permissions.json:

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

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