Ping查询协议 - 用于服务器列表

PingProtocol - 为 Hytale 实现的 Minecraft 服务器列表 Ping

一款 Hytale 插件，实现了 Minecraft 服务器列表 Ping 协议，允许 Minecraft 客户端查询您的 Hytale 服务器信息，并在其服务器列表中显示。

工作原理

此插件创建一个 TCP 服务器，与 Hytale 的 QUIC（UDP）游戏服务器并行运行。关键点是 TCP 和 UDP 是独立的协议，因此它们可以监听相同端口号而不会发生冲突：

• Hytale 服务器：使用 UDP/QUIC 协议监听端口 5520（或配置端口）处理游戏流量
• PingProtocol 插件：使用相同端口号的 TCP 协议处理 Minecraft Ping 请求

这使得 Minecraft 客户端可以 Ping 您的 Hytale 服务器，无需任何端口转发或额外的网络配置。

功能

• 完整的 Minecraft 协议支持：

  • 现代协议（1.7+）支持 JSON 状态响应
  • 传统协议（1.6）支持 §1 格式化响应
  • 非常古老的协议（Beta 1.8 – 1.3）支持

• 自动服务器信息：

  • 当前玩家数和最大玩家数
  • 包含名称和 UUID 的玩家列表
  • 从 Hytale 清单读取的服务器版本（例如 "2026.01.13"）

• 性能优化：

  • 智能响应缓存（1 秒缓存持续时间）
  • 玩家数量变化时缓存失效
  • 缓存请求的响应时间小于 10 毫秒

• 简单配置：

  • 自定义 MOTD 文本
  • 显示/隐藏玩家列表
  • 始终使用游戏服务器端口（无需额外配置）

安装

1. 从发布页面下载 PingProtocol-1.0.0.jar
2. 将其放入 Hytale 服务器的 mods/ 目录
3. 启动服务器或输入 /plugin load Hytalist:PingProtocol
4. 如有需要，在 mods/Hytalist_PingProtocol/config.json 中进行配置

配置

插件会在 mods/Hytalist_PingProtocol/ 目录下创建一个 config.json 文件：

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

配置选项

选项	默认值	描述
motd	""	显示给 Minecraft 客户端的每日消息（未设置则为空字符串）
showPlayerList	true	悬停在玩家数量时显示玩家列表

插件会自动：

• 使用与 Hytale 服务器相同的端口（TCP/UDP 可以共享同一端口）
• 报告协议版本 0 以指示非 Minecraft 服务器
• 从 Hytale 清单读取服务器版本并去除构建哈希（例如 "2026.01.13-dcad8778f" 变为 "2026.01.13"）

协议支持

现代协议（Minecraft 1.7+）

插件实现了完整的现代服务器列表 Ping 协议：

1. 握手数据包（0x00）：客户端发送协议版本、服务器地址、端口和下一个状态
2. 状态请求（0x00）：客户端请求服务器状态
3. 状态响应（0x00）：服务器发送包含版本、玩家、描述的 JSON
4. Ping 请求（0x01）：客户端发送时间戳
5. Pong 响应（0x01）：服务器回显时间戳并关闭连接

JSON 响应示例：

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

传统协议（Minecraft 1.6）

插件也支持旧版客户端的传统 Ping 协议：

• 检测 0xFE 0x01 0xFA 魔术字节
• 响应 0xFF 踢出数据包
• 格式：§1\0protocol\0version\0motd\0online\0max

非常古老的协议（Beta 1.8 – 1.3）

支持最古老的 Ping 协议：

• 检测 0xFE 魔术字节
• 响应 0xFF 踢出数据包
• 格式：motd§online§max

性能

该插件针对低延迟响应进行了优化：

• 响应缓存：状态响应缓存 1 秒
• 智能失效：玩家数量变化时缓存失效
• 典型响应时间：
  • 首次请求（缓存未命中）：约 10-50 毫秒
  • 缓存请求：小于 10 毫秒
  • 缓存避免了每次 Ping 时进行获取完整玩家列表和 JSON 序列化等昂贵操作

技术细节

架构

该插件使用 Netty（Hytale 服务器中已提供）创建 TCP 服务器：

1. PingServer：引导和管理 Netty 服务器
2. MinecraftPingHandler：处理数据包的有状态处理器
3. StatusCache：状态响应的共享缓存，以最小化昂贵操作
4. MinecraftProtocol：用于 VarInt 编解码和数据包读写的实用工具
5. StatusResponse：用于 JSON 序列化的数据类

为何能工作

Minecraft 服务器列表 Ping 使用 TCP，而 Hytale 使用基于 UDP 的 QUIC。由于它们是不同的传输协议，因此可以绑定到相同的端口号：

• TCP 数据包 → 由 PingProtocol 插件处理
• UDP 数据包 → 由 Hytale 的 QUIC 服务器处理

从源码构建

./gradlew jar

JAR 文件将创建在 build/libs/PingProtocol-1.0.0.jar。

故障排除

"Failed to start ping server on port X"

原因：另一个 TCP 服务正在使用该端口

解决方案：

• 检查是否有其他服务绑定到 TCP 端口
• 确保防火墙允许该端口的 TCP 连接
• 注意：该插件使用与 Hytale 相同的端口号，但使用 TCP（Hytale 使用 UDP）

Minecraft 客户端显示 "Can't connect to server"

原因：防火墙阻止 TCP 连接或插件未启动

解决方案：

• 检查服务器日志中插件是否成功启动
• 检查防火墙是否允许服务器端口的 TCP 流量
• 尝试在 Minecraft 中使用 IP:port 格式添加服务器

玩家列表不显示

原因：配置设置或没有在线玩家

解决方案：

• 在配置中设置 "showPlayerList": true
• 确保 Hytale 服务器上确实有玩家在线
• 仅当 currentPlayerCount > 0 时才显示玩家列表

Ping 响应时间慢

原因：缓存未生效或首次请求

解决方案：

• 首次请求会构建缓存，可能需要 10-50 毫秒
• 后续请求应小于 10 毫秒
• 缓存每秒或玩家数量变化时失效
• 如果持续缓慢，请检查 Hytale 服务器性能

致谢

• 实现基于 Minecraft 服务器列表 Ping 规范