PingProtocol - Minecraft Server List Ping for Hytale

A Hytale plugin that implements the Minecraft Server List Ping protocol, allowing Minecraft clients to query your Hytale server information and display it in their server list.

How It Works

This plugin creates a TCP server that runs alongside Hytale's QUIC (UDP) game server. The key insight is that TCP and UDP are separate protocols, so they can both listen on the same port number without conflicts:

Hytale Server: Uses UDP/QUIC protocol on port 5520 (or configured port) for game traffic
PingProtocol Plugin: Uses TCP on the same port number for Minecraft ping requests

This allows Minecraft clients to ping your Hytale server without any port forwarding or additional network configuration.

Features

Full Minecraft Protocol Support:
- Modern protocol (1.7+) with JSON status responses
- Legacy protocol (1.6) with §1 formatted responses
- Very old protocol (Beta 1.8 - 1.3) support
Automatic Server Information:
- Current player count and max players
- Player list with names and UUIDs
- Server version from Hytale manifest (e.g., "2026.01.13")
Performance Optimized:
- Smart response caching (1-second cache duration)
- Cache invalidates when player count changes
- Sub-10ms response time for cached requests
Simple Configuration:
- Custom MOTD text
- Show/hide player list
- Always uses game server port (no extra configuration needed)

Installation

Download PingProtocol-1.0.0.jar from releases
Place it in your Hytale server's mods/ directory
Start your server or type /plugin load Hytalist:PingProtocol
Configure in mods/Hytalist_PingProtocol/config.json if needed

Configuration

The plugin creates a config.json file in mods/Hytalist_PingProtocol/:

{
  "motd": "",
  "showPlayerList": true
}

Configuration Options

Option	Default	Description
`motd`	`""`	Message of the Day displayed to Minecraft clients (empty string if not set)
`showPlayerList`	`true`	Show player list when hovering over player count

The plugin automatically:

Uses the same port as your Hytale server (TCP/UDP can share the same port)
Reports protocol version 0 to indicate a non-Minecraft server
Reads the server version from Hytale's manifest and strips build hash (e.g., "2026.01.13-dcad8778f" becomes "2026.01.13")

Protocol Support

Modern Protocol (Minecraft 1.7+)

The plugin implements the full modern Server List Ping protocol:

Handshake Packet (0x00): Client sends protocol version, server address, port, and next state
Status Request (0x00): Client requests server status
Status Response (0x00): Server sends JSON with version, players, description
Ping Request (0x01): Client sends timestamp
Pong Response (0x01): Server echoes timestamp and closes connection

Example JSON response:

{
  "version": {
    "name": "2026.01.13",
    "protocol": 0
  },
  "players": {
    "max": 100,
    "online": 5,
    "sample": [
      {
        "name": "PlayerName",
        "id": "uuid-here"
      }
    ]
  },
  "description": {
    "text": "My Hytale Server"
  }
}

Legacy Protocol (Minecraft 1.6)

The plugin also supports legacy ping protocol for older clients:

Detects 0xFE 0x01 0xFA magic bytes
Responds with 0xFF kick packet
Format: §1\0protocol\0version\0motd\0online\0max

Very Old Protocol (Beta 1.8 - 1.3)

Supports the oldest ping protocol:

Detects 0xFE magic byte
Responds with 0xFF kick packet
Format: motd§online§max

Performance

The plugin is optimized for low-latency responses:

Response Caching: Status responses are cached for 1 second
Smart Invalidation: Cache is invalidated when player count changes
Typical Response Times:
- First request (cache miss): ~10-50ms
- Cached requests: <10ms
- Cache avoids expensive operations like fetching full player list and JSON serialization on every ping

Technical Details

Architecture

The plugin uses Netty (already available in Hytale server) to create a TCP server:

PingServer: Bootstrap and manages the Netty server
MinecraftPingHandler: Stateful handler that processes packets
StatusCache: Shared cache for status responses to minimize expensive operations
MinecraftProtocol: Utilities for VarInt encoding/decoding and packet reading/writing
StatusResponse: Data classes for JSON serialization

Why This Works

Minecraft Server List Ping uses TCP, while Hytale uses QUIC which runs over UDP. Since these are different transport protocols, they can both bind to the same port number:

TCP packets → Handled by PingProtocol plugin
UDP packets → Handled by Hytale's QUIC server

Building from Source

./gradlew jar

The JAR will be created in build/libs/PingProtocol-1.0.0.jar.

Troubleshooting

"Failed to start ping server on port X"

Cause: Another TCP service is using the port

Solution:

Check if another service is bound to the TCP port
Ensure your firewall allows TCP connections on the port
Note: The plugin uses the same port number as Hytale but on TCP (Hytale uses UDP)

Minecraft client shows "Can't connect to server"

Cause: Firewall blocking TCP connections or plugin not started

Solution:

Verify the plugin started successfully in server logs
Check firewall allows TCP traffic on the server port
Try adding server using IP:port format in Minecraft

Player list not showing

Cause: Config setting or no players online

Solution:

Set "showPlayerList": true in config
Ensure players are actually online on the Hytale server
Player list is only shown when currentPlayerCount > 0

Slow ping response times

Cause: Cache not working or first request

Solution:

First request builds the cache and may take 10-50ms
Subsequent requests should be <10ms
Cache invalidates every second or when player count changes
If consistently slow, check Hytale server performance

Credits

Implementation based on Minecraft Server List Ping specification

Ping Query Protocol - For Server Lists