HGS-查询 - 新手盒子

.detail-panel[hidden] { display: block !important; } .detail-tabs { display: none; } /* These three panels are rendered by the browser. */ [data-versions], [data-changelog-panel], [data-comments] { display: none; }

HGS 查询插件

官方 Hytale 服务器插件，适用于 HytaleGameServers.net——Hytale 的顶级服务器列表平台。

该插件通过定期向 API 发送服务器状态、玩家数量及其他元数据，保持你在 HytaleGameServers.net 上的服务器列表最新。

✨ 特色

🔄 自动状态更新 ——实时玩家数量、MOTD、世界信息等信息会发送到你的服务器列表
🌐 网络模式 — 将多台 Hytale 服务器作为单一列表运行，支持自动控制器选择和点对点 TCP 通信
⚡ 完全异步 ——所有 API 调用和网络 I/O 都运行在异步线程上，对游戏玩法没有影响
🔒 安全通信 — 带有承载令牌认证的 HTTPS
🛡️ 隐私控制 ——切换共享的数据：玩家用户名、系统环境、安装插件
📊 动态间隔 ——默认为 3 分钟更新一次（赞助/实时服务器为 1 分钟）——比网站内置的查询端口轮询更快

📦 安装

从 Releases 下载最新发布
把 JAR 放到你 Hytale 服务器的 mod/ 目录里
启动你的服务器——配置文件会在 mods/HGS_Query/
创建账户并注册服务器列表 HytaleGameServers.net
从服务器仪表盘复制你的服务器 ID 和 API 令牌
把它们粘贴到 mod/HGS_Query/Api.json
重启你的服务器

⚙️ 配置

`Api.json`

你的服务器凭证。HytaleGameServers.net 从你的服务器仪表盘获取这些数据。

{
  "serverId": "YOUR_SERVER_ID_HERE",
  "apiToken": "YOUR_API_TOKEN_HERE"
}

🔑 保持你的 API 令牌私密。不要公开分享或提交版本控制。

`Config.json`

通用插件设置和隐私控制。

背景设定	默认	描述
`enabled`	`true`	主开关 — 设置为 `false` 以禁用所有 API 通信
`sendSystemEnvironmentName`	`true`	在更新中包含操作系统名称（例如“Windows 10”、“Linux”）。
`sendOnlinePlayerUsernames`	`true`	请包含每个玩家的用户名（玩家数量始终会被发送）
`sendPluginInfo`	`true`	包含已安装的插件列表（仅包含组、名称和版本）

`Network.json`（仅限多服务器）

只有当你同时运行多个 Hytale 服务器作为一个列表时才需要。

背景设定	默认	描述
`enabled`	`false`	启用网络模式
`nodeId`	`"DEFAULT"`	`该节点的唯一标识符（例如 LOBBY、SURVIVAL-1、FACTIONS）`
`port`	`9800`	TCP 端口用于节点间通信
`nodes`	`[]`	“`host：port”` 格式的对等地址列表（不包括此节点）

网络模式的工作原理：

**每个节点运行一台 TCP 服务器，并连接到所有配置好的节点。心跳每 5 秒追踪一次活泼。nodeId（字典序）最小的节点自动被选为控制器。控制器从所有节点收集快照，并向 HGS API 发送一次聚合更新。**

如果控制器宕机，会自动选举新的控制器——无需人工干预。

示例——3个服务器网络：

在 LOBBY（端口 9800）上：

{
  "enabled": true,
  "nodeId": "LOBBY",
  "port": 9800,
  "nodes": ["192.168.1.11:9800", "192.168.1.12:9800"]
}

关于生存 （192.168.1.11）：

{
  "enabled": true,
  "nodeId": "SURVIVAL",
  "port": 9800,
  "nodes": ["192.168.1.10:9800", "192.168.1.12:9800"]
}

关于派系 （192.168.1.12）：

{
  "enabled": true,
  "nodeId": "FACTIONS",
  "port": 9800,
  "nodes": ["192.168.1.10:9800", "192.168.1.11:9800"]
}

⚠️ 所有节点必须在 Api.json 共享相同的 serverID 和 apiToken。

📋 收集的数据

插件向 HytaleGameServers.net 发送以下内容：

服务器名称、MOTD、地址和端口
当前及最大玩家人数
在线玩家用户名和 UUID（如果启用的话）
世界名称与伯爵
服务器实现版本
已安装的插件——仅限组、名称和版本（如果启用）
系统环境名称（如果启用的话）
密码保护状态（仅布尔值——密码从未传输）
服务器启动时间戳

当服务器离线时，所有数据都会自动清除。

🔗 API 端点

该插件仅与以下用户通信：

POST https://hytalegameservers.net/api/plugin/query/update —— 状态更新
POST https://hytalegameservers.net/api/plugin/query/shutdown ——优雅的关机通知

⏱️ 更新间隔

服务器列表保持最新有两种方式—— **插件（本项目）和网站内置的查询端口轮询 **。插件更快且优先。

方法	默认间隔	赞助 / 实时
插件（推荐）	3分钟	1分钟
查询端口（网站端）	5分钟	1分钟

当插件主动与 API 同步时，网站后端不会查询服务器的查询端口——插件会完全接管。查询端口轮询只适用于未安装该插件的服务器。

📝 要求

Hytale 服务器（官方发布）
Java 21+
HytaleGameServers.net 上的账号和服务器列表
对 hytalegameservers.net 的出站 HTTPS 访问

🔨 源头建设

git clone https://github.com/HytaleGameServers/Query-Plugin.git
cd Query-Plugin
mvn clean package

编译后的 JAR 会放在目标/ 目录中。

💬 支持

🌐 网站： hytalegameservers.net
💬 Discord： hytalegameservers.net/discord

<br

⚠️ 重要通知

严格禁止滥用 API 或插件。这包括试图绕过速率限制、发送伪造数据、恶意逆向工程，或违反服务条款的其他行为。违规将导致您的服务器列表和账户被暂停或永久终止。

这是一个非官方的社区项目。Hytale 是 Hypixel Studios 的商标。