One Query

OneQuery - Hytale Server Query Plugin

A lightweight UDP query protocol plugin for Hytale servers. Query your server status without HTTP overhead.

Features

• []UDP Protocol - Runs on the same port as your game server, no extra ports needed

  []Zero Dependencies - Standalone plugin with no external requirements

  []Secure - Challenge-response authentication prevents amplification attacks

  []Network Mode - Combine player counts across multiple servers via Redis

  []Access Control - Token-based authentication for protected endpoints

  []Server List Integration - Auto-register with hytale.one

  Installation

  • []Download the latest release from the Releases page

    []Drop onequery-x.x.x.jar into your server's plugins folder

    []Restart your server

    Quick Start

    The plugin works immediately with sensible defaults. Most single-server setups require no configuration at all.

    Configuration

    Config location: plugins/OneQuery/config.json

    "Enabled": true,

    "LegacyProtocolEnabled": true

    Basic Options

    • []Enabled (default: true) - Toggle the query protocol on/off

      []LegacyProtocolEnabled (default: true) - Support V1 protocol for older clients

      Network Mode

      Combine data across multiple servers using Redis. Ideal for server networks wanting to display combined player counts and lists.

      Why Use Network Mode?

      • []Display total players across all servers

        []Show a combined player list from your lobby

        []Track players across your network in real-time

        Network Configuration

        "Network": {

        "Enabled": true,

        "ServerId": "survival-1",

        "NetworkId": "my-network",

        "Mode": "AGGREGATE",

        "Type": "redis",

        "Host": "redis.example.com",

        "Port": 6379,

        "Username": "optional",

        "Password": "optional",

        "Database": 0,

        "UseTLS": false

        Network Options

        • []Enabled (default: false) - Turn on network mode

          []ServerId (default: "server-1") - Unique ID for this server within the network

          []NetworkId (default: "default") - Groups servers together; only matching NetworkIds share data

          []Mode (default: "AGGREGATE") - How this server participates (see modes below)

          []Store. Type (default: "redis") - Storage backend (currently only redis)

          []Store. Redis. Host (default: "localhost") - Redis hostname

          []Store. Redis. Port (default: 6379) - Redis port

          []Store. Redis. Username - Redis ACL username (Redis 6+)

          []Store. Redis. Password - Redis password

          []Store. Redis. Database (default: 0) - Redis database number

          []Store. Redis. UseTLS (default: false) - Enable TLS/SSL

          Network Modes Explained

          • []PUBLISH - Only reports server state to Redis

            []SYNC - Publishes and receives updates from other servers

            []AGGREGATE - Syncs and returns combined data in query responses

            Example: Game Server (Publish Only)

            Game servers just need to publish their state. They don't need awareness of other servers.

            "Network": {

            "Enabled": true,

            "ServerId": "survival-1",

            "NetworkId": "my-network",

            "Mode": "PUBLISH",

            "Type": "redis",

            "Redis": { "Host": "redis.local" }

            Example: Lobby Server (Aggregate)

            Lobby servers aggregate data from all servers and return combined stats.

            "Network": {

            "Enabled": true,

            "ServerId": "lobby-1",

            "NetworkId": "my-network",

            "Mode": "AGGREGATE",

            "Type": "redis",

            "Redis": { "Host": "redis.local" }

            Plugin API

            Other plugins can access network data via the OneQuery API. Requires SYNC