本文将涵盖Hytale独立服务器的安装、配置与运行相关内容。
Hytale 服务器可以在任何拥有至少 4GB 内存并安装了 Java 25 的设备上运行。支持 x64 和 arm64 架构。
我们建议在服务器使用时监控 RAM 和 CPU 的使用情况，以了解在您的玩家数量和玩法模式下典型的资源消耗——资源使用量在很大程度上取决于玩家行为。
通用指导：
请安装 Java 25。我们推荐使用 Adoptium。
确认安装
通过运行以下命令来验证安装：
预期输出：
有两种获取服务器文件的方式：
从启动器手动复制
在您的启动器安装文件夹中找到这些文件：
列出目录内容：
预期输出：
将
Hytale Downloader CLI工具
这是一个通过 OAuth2 身份验证下载 Hytale 服务器和资源文件的命令行工具。请参阅压缩包内的 QUICKSTART.md 文件。
下载地址： hytale-downloader.zip (Linux & Windows)
使用以下命令启动服务器：
（译注：将 PathToAssets.zip 更换为 Assets.zip 的文件位置）
首次启动后，需要为您的服务器进行身份验证。
完成身份验证后，您的服务器即可接受玩家连接。
额外身份验证信息
Hytale 服务器需要进行身份验证，以便能够与我们的服务 API 通信并防止滥用。
如果您需要为大量服务器进行身份验证，或者需要自动动态地对服务器进行身份验证，请等待关于“服务器提供商身份验证”文章以获取详细信息。
查看所有可用参数：
预期输出：
默认端口是 5520。可以使用
Hytale 使用 基于 UDP 的 QUIC 协议（不是 TCP）。请相应地配置您的防火墙和端口转发。
端口转发
如果在路由器后托管，请将 UDP 端口 5520（或您的自定义端口）转发到您的服务器机器。无需转发 TCP 端口。
防火墙规则
Windows Defender 防火墙：
Linux (iptables)：
Linux (ufw)：
NAT 注意事项
在大多数情况下，QUIC 能很好地处理 NAT 穿透。如果玩家连接遇到问题：
Universe 结构
universe/worlds/ 目录包含所有可玩的世界。每个世界都有自己的 config.json：
从诸如 CurseForge 等来源下载模组（.zip 或 .jar 文件），并将其放入 mods/ 文件夹。
我们使用 Sentry 来追踪崩溃。使用 --disable-sentry 参数禁用它，以避免提交您的开发错误：
服务器附带一个预训练的 AOT 缓存 (HytaleServer.aot)，通过跳过 JIT 预热来改善启动时间。参阅 JEP-514。
我们的开发合作伙伴 Nitrado 和 Apex Hosting 维护了一些满足常见服务器托管需求的插件：
视距是内存使用量的主要驱动因素。出于性能和游戏体验考虑，我们建议将最大视距限制在 12 区块（384 方块）。
作为对比：Minecraft 服务器默认视距为 10 区块（160 方块）。Hytale 默认的 384 方块大致相当于 24 个 Minecraft 区块。使用默认设置时，请预期更高的内存使用量——请根据您预期的玩家数量调整此值。
Hytale 支持在服务器之间路由玩家的原生机制。无需使用类似 BungeeCord 的反向代理。
将已连接的玩家转移到另一个服务器。原服务器发送一个转介数据包，其中包含目标主机、端口和一个可选的有效负载（最多 4KB）。客户端将向目标服务器建立新连接，并在握手期间提交该有效负载。
应用场景： 在游戏服务器间转移玩家、传递会话上下文、通过匹配机制控制访问。
在连接握手期间，服务器可以拒绝玩家并将其重定向到另一个服务器。客户端将自动连接到重定向的地址。
应用场景：负载均衡、区域服务器路由、强制要求先连接大厅。
当玩家意外断开连接（服务器崩溃、网络中断）时，客户端将自动重新连接到一个预先配置的故障转移服务器，而不是返回主菜单。
应用场景：游戏服务器崩溃后将玩家送回大厅、在重启期间保持玩家参与度。
可以使用 Netty QUIC 构建自定义代理服务器。Hytale 专门使用 QUIC 进行客户端与服务器通信。
数据包定义和协议结构存放于 HytaleServer.jar 中：
使用它们可以在客户端和后端服务器之间解码、检查、修改或转发通信流量。
关于控制堆大小的 -Xms 和 -Xmx 等主题，请参阅 JVM 重要参数指南。
Hytale 协议使用哈希值来验证客户端与服务器的兼容性。如果哈希值不完全匹配，连接将被拒绝。
配置文件（config.json、permissions.json 等）在服务器启动时读取，并在发生游戏内操作（例如，通过命令分配权限）时写入。在服务器运行时手动更改这些文件很可能会被覆盖。
HytaleServer 的 jar 包将发布到 Maven Central，以便在模组项目中作为依赖项使用。
包括版本控制在内的具体细节将在发布时确定。请查看模组社区资源，获取关于使用这些依赖项的最新信息。
在游戏主菜单中可访问的发现目录，玩家可以浏览和查找服务器及小游戏。服务器运营商可以选择加入此目录，直接向玩家推广他们的内容。
列表要求：
玩家数量验证：
在服务器发现功能中显示的玩家数量是通过客户端遥测数据收集的，而非服务器报告的数据。这可以防止人数造假，并确保玩家在浏览服务器时能够信任所看到的数字。对于在服务器发现功能外手动添加的服务器，仍然可以向用户报告一个未经验证的玩家数量。
一个允许玩家组队并在服务器转移和小游戏排队过程中保持在一起的队伍系统。
与服务器发现的集成：
玩家可以与他们的队伍一起浏览服务器并共同加入。加入前即可看到队伍人数要求和限制，以便团体提前知道他们是否可以一起玩。
该系统为无缝的社交体验奠定了基础，使朋友可以作为一个团体在 Hytale 生态系统中移动，而无需手动协调。
客户端内置的支付网关，服务器可以用其接受玩家的付款。此功能为可选，但鼓励使用。
对服务器运营商的益处：
对玩家的益处：
SRV 记录允许玩家使用域名（例如，play.example.com）进行连接，而无需指定端口，DNS 会处理查找并解析实际的服务器地址和端口。
当前状态： 不支持。正在评估中。
目前不可用的原因：
目前没有经过实战检验的 C# 库可用于 SRV 记录解析。现有的选项要么需要引入完整的 DNS 客户端实现，这会带来不必要的复杂性和潜在稳定性风险；要么缺乏我们核心网络功能所需的生产就绪度。
我们正在评估替代方案，将在有合适解决方案时重新考虑此功能。
经过身份验证的服务器将能够访问用于玩家数据、版本控制和服务器操作的官方 API 端点。这些端点减少了对第三方服务的需求，并直接从 Hytale 提供权威数据。
计划中的端点：
考虑中：
设计目标：
目录
| 章节 | 主题 |
| 服务器安装 | Java 安装、服务器文件、系统要求 |
| 运行 Hytale 服务器 | 启动命令、身份验证、端口、防火墙、文件结构 |
| 技巧与窍门 | 模组、AOT 缓存、Sentry、推荐插件、视距 |
| 多服务器架构 | 玩家转介、重定向、故障转移、构建代理 |
| 其他详情 | JVM 参数、协议更新、配置文件 |
| 未来新增功能 | 服务器发现、队伍、集成支付、SRV记录、API端点 |
服务器安装
Hytale 服务器可以在任何拥有至少 4GB 内存并安装了 Java 25 的设备上运行。支持 x64 和 arm64 架构。
我们建议在服务器使用时监控 RAM 和 CPU 的使用情况，以了解在您的玩家数量和玩法模式下典型的资源消耗——资源使用量在很大程度上取决于玩家行为。
通用指导：
| 资源 | 主要驱动因素 |
| CPU | 大量玩家或实体数量（NPC、生物） |
| RAM | 大面积加载的世界区域（高视距、玩家独立探索） |
安装 Java 25
请安装 Java 25。我们推荐使用 Adoptium。
确认安装
通过运行以下命令来验证安装：
代码:
java --version预期输出：
代码:
openjdk 25.0.1 2025-10-21 LTS
OpenJDK Runtime Environment Temurin-25.0.1+8 (build 25.0.1+8-LTS)
OpenJDK 64-Bit Server VM Temurin-25.0.1+8 (build 25.0.1+8-LTS, mixed mode, sharing)服务器文件
有两种获取服务器文件的方式：
- 从启动器安装目录手动复制
- 使用 Hytale Downloader CLI 工具
从启动器手动复制
在您的启动器安装文件夹中找到这些文件：
代码:
Windows: %appdata%\Hytale\install\release\package\game\latest
Linux: $XDG_DATA_HOME/Hytale/install/release/package/game/latest
MacOS: ~/Application Support/Hytale/install/release/package/game/latest列出目录内容：
代码:
ls预期输出：
代码:
Directory: C:\Users\...\Hytale\install\release\package\game\latest
Mode LastWriteTime Length Name
---- ------------- ------ ----
d----- 12/25/2025 9:25 PM Client
d----- 12/25/2025 9:25 PM Server
-a---- 12/25/2025 9:04 PM 3298097359 Assets.zip将
Server 文件夹和 Assets.zip 复制到您的目标服务器文件夹。Hytale Downloader CLI工具
这是一个通过 OAuth2 身份验证下载 Hytale 服务器和资源文件的命令行工具。请参阅压缩包内的 QUICKSTART.md 文件。
下载地址： hytale-downloader.zip (Linux & Windows)
| 命令 | 描述 |
| ./hytale-downloader | 下载最新版本 |
| ./hytale-downloader -print-version | 显示游戏版本（不下载） |
| ./hytale-downloader -version | 显示 hytale-downloader 版本 |
| ./hytale-downloader -check-update | 检查 hytale-downloader 更新 |
| ./hytale-downloader -download-path game.zip | 下载到指定文件 |
| ./hytale-downloader -patchline pre-release | 从预发布通道下载 |
| ./hytale-downloader -skip-update-check | 跳过自动更新检查 |
运行 Hytale 服务器
使用以下命令启动服务器：
代码:
java -jar HytaleServer.jar --assets PathToAssets.zip（译注：将 PathToAssets.zip 更换为 Assets.zip 的文件位置）
身份验证
首次启动后，需要为您的服务器进行身份验证。
代码:
> /auth login device
===================================================================
DEVICE AUTHORIZATION
===================================================================
Visit: https://accounts.hytale.com/device
Enter code: ABCD-1234
Or visit: https://accounts.hytale.com/device?user_code=ABCD-1234
===================================================================
Waiting for authorization (expires in 900 seconds)...
[User completes authorization in browser]
> Authentication successful! Mode: OAUTH_DEVICE完成身份验证后，您的服务器即可接受玩家连接。
额外身份验证信息
Hytale 服务器需要进行身份验证，以便能够与我们的服务 API 通信并防止滥用。
如果您需要为大量服务器进行身份验证，或者需要自动动态地对服务器进行身份验证，请等待关于“服务器提供商身份验证”文章以获取详细信息。
帮助
查看所有可用参数：
代码:
java -jar HytaleServer.jar --help预期输出：
代码:
选项 描述
------ -----------
--accept-early-plugins 确认加载早期插件是不受支持的行为，可能导致稳定性问题
--allow-op
--assets <路径> 资源目录 (默认：..\HytaleAssets)
--auth-mode <authenticated|offline> 身份验证模式 (默认：AUTHENTICATED)
-b, --bind <InetSocketAddress> 监听地址 (默认：0.0.0.0:5520)
--backup 启用自动备份
--backup-dir <路径> 备份目录
--backup-frequency <整数> 备份间隔（分钟）(默认：30)
[...]端口
默认端口是 5520。可以使用
--bind 参数更改端口：
代码:
java -jar HytaleServer.jar --assets Assets.zip的路径 --bind 0.0.0.0:25565防火墙和网络配置
Hytale 使用 基于 UDP 的 QUIC 协议（不是 TCP）。请相应地配置您的防火墙和端口转发。
端口转发
如果在路由器后托管，请将 UDP 端口 5520（或您的自定义端口）转发到您的服务器机器。无需转发 TCP 端口。
防火墙规则
Windows Defender 防火墙：
代码:
New-NetFirewallRule -DisplayName "Hytale Server" -Direction Inbound -Protocol UDP -LocalPort 5520 -Action AllowLinux (iptables)：
代码:
sudo iptables -A INPUT -p udp --dport 5520 -j ACCEPTLinux (ufw)：
代码:
sudo ufw allow 5520/udpNAT 注意事项
在大多数情况下，QUIC 能很好地处理 NAT 穿透。如果玩家连接遇到问题：
- 确保端口转发专门针对 UDP，而不是 TCP。
- 对称 NAT 配置可能导致问题——考虑使用 VPS 或独立服务器。
- 处于运营商级 NAT（手机网络常见）后的玩家作为客户端应该可以正常连接。
文件结构
| 路径 | 描述 |
| .cache/ | 优化文件的缓存 |
| logs/ | 服务器日志文件 |
| mods/ | 已安装的模组 |
| universe/ | 世界和玩家存档数据 |
| bans.json | 被封禁的玩家 |
| config.json | 服务器配置 |
| permissions.json | 权限配置 |
| whitelist.json | 白名单玩家 |
Universe 结构
universe/worlds/ 目录包含所有可玩的世界。每个世界都有自己的 config.json：
代码:
{
"Version": 4,
"UUID": {
"$binary": "j2x/idwTQpen24CDfH1+OQ==",
"$type": "04"
},
"Seed": 1767292261384,
"WorldGen": {
"Type": "Hytale",
"Name": "Default"
},
"WorldMap": {
"Type": "WorldGen"
},
"ChunkStorage": {
"Type": "Hytale"
},
"ChunkConfig": {},
"IsTicking": true,
"IsBlockTicking": true,
"IsPvpEnabled": false,
"IsFallDamageEnabled": true,
"IsGameTimePaused": false,
"GameTime": "0001-01-01T08:26:59.761606129Z",
"RequiredPlugins": {},
"IsSpawningNPC": true,
"IsSpawnMarkersEnabled": true,
"IsAllNPCFrozen": false,
"GameplayConfig": "Default",
"IsCompassUpdating": true,
"IsSavingPlayers": true,
"IsSavingChunks": true,
"IsUnloadingChunks": true,
"IsObjectiveMarkersEnabled": true,
"DeleteOnUniverseStart": false,
"DeleteOnRemove": false,
"ResourceStorage": {
"Type": "Hytale"
},
"Plugin": {}
}技巧与窍门
安装模组
从诸如 CurseForge 等来源下载模组（.zip 或 .jar 文件），并将其放入 mods/ 文件夹。
禁用 Sentry 崩溃报告
我们使用 Sentry 来追踪崩溃。使用 --disable-sentry 参数禁用它，以避免提交您的开发错误：
代码:
java -jar HytaleServer.jar --assets Assets.zip的路径 --disable-sentry利用预编译缓存
服务器附带一个预训练的 AOT 缓存 (HytaleServer.aot)，通过跳过 JIT 预热来改善启动时间。参阅 JEP-514。
代码:
java -XX:AOTCache=HytaleServer.aot -jar HytaleServer.jar --assets Assets.zip的路径推荐插件
我们的开发合作伙伴 Nitrado 和 Apex Hosting 维护了一些满足常见服务器托管需求的插件：
| 插件 | 描述 |
| Nitrado:WebServer | 用于 Web 应用和 API 的基础插件 |
| Nitrado:Query | 通过 HTTP 暴露服务器状态（玩家数量等） |
| Nitrado:PerformanceSaver | 根据资源使用情况动态限制视距 |
| ApexHosting:PrometheusExporter | 暴露详细的服务器和 JVM 指标 |
视距
视距是内存使用量的主要驱动因素。出于性能和游戏体验考虑，我们建议将最大视距限制在 12 区块（384 方块）。
作为对比：Minecraft 服务器默认视距为 10 区块（160 方块）。Hytale 默认的 384 方块大致相当于 24 个 Minecraft 区块。使用默认设置时，请预期更高的内存使用量——请根据您预期的玩家数量调整此值。
多服务器架构
Hytale 支持在服务器之间路由玩家的原生机制。无需使用类似 BungeeCord 的反向代理。
玩家转介
将已连接的玩家转移到另一个服务器。原服务器发送一个转介数据包，其中包含目标主机、端口和一个可选的有效负载（最多 4KB）。客户端将向目标服务器建立新连接，并在握手期间提交该有效负载。
代码:
PlayerRef.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)安全警告： 有效负载是通过客户端传输的，可能被篡改。请使用加密方式（例如，使用共享密钥的 HMAC）对有效负载进行签名，以便接收服务器能够验证其真实性。
应用场景： 在游戏服务器间转移玩家、传递会话上下文、通过匹配机制控制访问。
连接重定向
在连接握手期间，服务器可以拒绝玩家并将其重定向到另一个服务器。客户端将自动连接到重定向的地址。
代码:
PlayerSetupConnectEvent.referToServer(@Nonnull final String host, final int port, @Nullable byte[] data)应用场景：负载均衡、区域服务器路由、强制要求先连接大厅。
断开连接故障转移
当玩家意外断开连接（服务器崩溃、网络中断）时，客户端将自动重新连接到一个预先配置的故障转移服务器，而不是返回主菜单。
应用场景：游戏服务器崩溃后将玩家送回大厅、在重启期间保持玩家参与度。
构建代理服务器
可以使用 Netty QUIC 构建自定义代理服务器。Hytale 专门使用 QUIC 进行客户端与服务器通信。
数据包定义和协议结构存放于 HytaleServer.jar 中：
代码:
com.hypixel.hytale.protocol.packets使用它们可以在客户端和后端服务器之间解码、检查、修改或转发通信流量。
其他详情
Java 命令行参数
关于控制堆大小的 -Xms 和 -Xmx 等主题，请参阅 JVM 重要参数指南。
协议更新
Hytale 协议使用哈希值来验证客户端与服务器的兼容性。如果哈希值不完全匹配，连接将被拒绝。
配置文件
配置文件（config.json、permissions.json 等）在服务器启动时读取，并在发生游戏内操作（例如，通过命令分配权限）时写入。在服务器运行时手动更改这些文件很可能会被覆盖。
Maven Central 构件
HytaleServer 的 jar 包将发布到 Maven Central，以便在模组项目中作为依赖项使用。
代码:
<dependency>
<groupId>com.hypixel.hytale</groupId>
<artifactId>Server</artifactId>
</dependency>包括版本控制在内的具体细节将在发布时确定。请查看模组社区资源，获取关于使用这些依赖项的最新信息。
未来新增功能
服务器与小游戏发现
在游戏主菜单中可访问的发现目录，玩家可以浏览和查找服务器及小游戏。服务器运营商可以选择加入此目录，直接向玩家推广他们的内容。
列表要求：
| 要求 | 描述 |
| 服务器运营商准则 | 服务器必须遵守运营商准则和社区标准 |
| 自我评级 | 运营商必须准确评定其服务器内容。评级支持内容过滤和家长控制 |
| 执行措施 | 违反自我评级的服务器将根据服务器运营商政策受到相应的执行措施 |
玩家数量验证：
在服务器发现功能中显示的玩家数量是通过客户端遥测数据收集的，而非服务器报告的数据。这可以防止人数造假，并确保玩家在浏览服务器时能够信任所看到的数字。对于在服务器发现功能外手动添加的服务器，仍然可以向用户报告一个未经验证的玩家数量。
队伍系统
一个允许玩家组队并在服务器转移和小游戏排队过程中保持在一起的队伍系统。
与服务器发现的集成：
玩家可以与他们的队伍一起浏览服务器并共同加入。加入前即可看到队伍人数要求和限制，以便团体提前知道他们是否可以一起玩。
该系统为无缝的社交体验奠定了基础，使朋友可以作为一个团体在 Hytale 生态系统中移动，而无需手动协调。
集成支付系统
客户端内置的支付网关，服务器可以用其接受玩家的付款。此功能为可选，但鼓励使用。
对服务器运营商的益处：
- 无需处理支付详情或构建基础设施即可接受付款
- 交易通过受信任的安全系统处理
对玩家的益处：
- 无需访问外部网站
- 所有交易都是安全且可追溯的
- 支付信息保留在 Hytale 生态系统内
SRV 记录支持
SRV 记录允许玩家使用域名（例如，play.example.com）进行连接，而无需指定端口，DNS 会处理查找并解析实际的服务器地址和端口。
当前状态： 不支持。正在评估中。
目前不可用的原因：
目前没有经过实战检验的 C# 库可用于 SRV 记录解析。现有的选项要么需要引入完整的 DNS 客户端实现，这会带来不必要的复杂性和潜在稳定性风险；要么缺乏我们核心网络功能所需的生产就绪度。
我们正在评估替代方案，将在有合适解决方案时重新考虑此功能。
第一方 API 端点
经过身份验证的服务器将能够访问用于玩家数据、版本控制和服务器操作的官方 API 端点。这些端点减少了对第三方服务的需求，并直接从 Hytale 提供权威数据。
计划中的端点：
| 端点 | 描述 |
| UUID ↔ 名称查询 | 解析玩家名称和 UUID。支持单次和批量查询 |
| 游戏版本 | 查询当前游戏版本、协议版本，并检查更新 |
| 玩家资料 | 获取玩家资料数据，包括装饰品、头像渲染和公开资料信息 |
| 服务器遥测 | 报告服务器状态、玩家数量和元数据，用于发现功能集成 |
| 举报 | 举报玩家违反服务条款的行为 |
| 支付 | 使用我们内置的支付网关处理付款 |
考虑中：
| 端点 | 描述 |
| 全局封禁查询 | 查询玩家是否受到平台级别的制裁（非服务器特定封禁） |
| 好友列表 | 获取玩家的好友列表（需获得适当权限），用于社交功能 |
| Webhook 订阅 | 订阅推送通知，用于接收诸如玩家名称变更或制裁更新等事件 |
设计目标：
- 宽松的速率限制： 支持批量操作的端点和利于缓存的响应，以支持大型网络
- 认证访问： 所有端点都需要服务器身份验证以防止滥用
- 版本化 API： 稳定的合约，并在进行破坏性变更时提供弃用窗口
最后编辑:
