[未提供需要翻译的文本，请提供待翻译内容]

Chunksmith

需要帮助或发现了漏洞？ 请在 Chunksmith 支持论坛 报告。

Chunksmith 是一款 Minecraft 区块预生成器，能够快速、高效且 安全 地生成区块。除了快速的预生成功能外，它还增加了自适应 I/O 节流（即使在有玩家在线时也能全天候持续生成）、区域写入反压保护以及世界生成诊断（超限检测和结构故障归因）。

作为一个 Fabric、Forge 和 NeoForge 模组 以及一个 Paper / Spigot / Folia 插件 发布。最初源自 pop4959 的 Chunky；现已独立开发。采用 GPL-3.0 许可。

源代码： CSv3 分支 —— 当前开发中的 3.x 系列。2.x 系列已冻结于 CSv2_archive。

为什么选择 Chunksmith

• 快速。 预先生成区块，使其在玩家到达前准备就绪，消除按需生成带来的卡顿。
• 负载下安全。 自适应节流器监控服务器刻健康度并自动降速，因此玩家在线时也能进行生成而不会导致 TPS 下降。
• 形状灵活。 支持正方形、圆形、菱形、三角形、星形等多种形状——以坐标、世界出生点或世界边界为中心，按半径或直径设置。
• 多世界，带有实时进度、速率、预估完成时间以及可选的 Boss 血条。
• 可恢复。 暂停、继续、取消以及重启后继续——进度会被保存。
• 世界裁剪。 删除选定区域外的区块。
• 默认启用 LOD 生成。 安装 Distant Horizons 或 Voxy 后，Chunksmith 会在预生成时构建其远距离视野数据。无需事先寻找配置文件——见下文。
• 重新运行会自动填充 LOD 空洞。 在安装渲染器之前预生成了世界？再次运行相同的预生成任务，Chunksmith 会从已有的区块构建 LOD——它不会重新生成区块，并且会跳过所有已完成的部分。
• 内置多人游戏 LOD。 加入服务器的玩家会下载预生成的 LOD 数据，无需亲自探索即可看到整个远距离世界。无需配套模组 —— 同一个 Chunksmith jar 文件在服务端和客户端上都能完成此工作。
• 面向开发者的 API，用于生成进度和完成事件。

LOD：查看你预生成的内容

Chunksmith 在预生成时会以其自身的中立格式（CSLOD）发出细节层次数据，并将其直接传递给 LOD 渲染器。

它会自动启用

如果安装了 LOD 渲染器，LOD 生成就处于开启状态。 服务端启动时，Chunksmith 会查找游戏中的 Distant Horizons、Voxy 或 Voxy 分支。如果存在其中之一，它会在预生成时构建 LOD 数据。无需寻找配置键，无需手动开启，也不会出现“为什么没有 LOD？”的情况——安装渲染器，安装 Chunksmith，进行预生成，远距离地形就会呈现。

在专用服务端上，它也处于开启状态，这是唯一一种本地无法绘制 LOD 的情况：专用服务端本身不运行任何渲染器，但它构建的存储正是提供给玩家使用的内容（参见下面的多人游戏部分）。构建它是其存在的全部原因。

如果游戏中没有能够使用 LOD 数据的内容——没有渲染器，也不是专用服务端——Chunksmith 不会生成任何 LOD 数据，并且会在日志中明确说明，而不会让你猜测。

在单人游戏中，Chunksmith 是你唯一需要的模组。 集成服务端在你的游戏内部运行，因此 Chunksmith 会直接将 LOD 注入到你的渲染器中——无需配套模组，无需网络。它会注册为 Distant Horizons 的世界生成器覆盖（lodDhOverride），因此 DH 会显示你预生成的区域而无需自行生成任何内容，并且 /cslod dhpush 命令会按需将现有存储重新注入到 DH 中——在你安装 DH 很久之前预生成的世界，可以在事后获得其 LOD，无需重新生成。如果存在 voxy，/cslod inject 命令会为 voxy 执行相同的操作。

在多人游戏中，LOD 数据必须到达玩家手中——从 3.1.0-beta-1 版本开始，Chunksmith 自己就能做到这一点。 将相同的 jar 文件放在服务端和客户端。服务端保存 CSLOD 存储；客户端下载所需内容并将其提供给该玩家的 Distant Horizons 或 voxy。不再需要配套模组。

数据以网络速度传输。该存储已经是普通的区域文件，因此服务端不会流式传输它们——而是通过游戏端口 +1 上的 HTTP 回传通道提供它们，该通道会自动打开，无需你进行任何配置。如果该端口无法绑定或无法访问，Chunksmith 会发出提示，并通过游戏连接以较慢的速度逐字节传输相同的数据：速度较慢，但始终有效，并且绝不会中断会话。

• 存储即是缓存。 重新加入游戏时，不会重复下载任何内容。
• 它会跟随你。 走向服务端已预生成但尚未发送的地形时，数据会在途中被获取——拉取操作并非仅在加入时一次性完成。
• 它只发送你能绘制的内容。 客户端会告知服务端其渲染器的实际 LOD 距离，服务端仅会传送该距离内的区域，而不会发送更多。
• 它会自动保持同步。 在你游戏过程中，客户端和服务端每隔几分钟会比较一个小的校验和；如果它们不一致，客户端仅会获取发生变化的部分。持续进行的预生成任务刚刚完成的地形会无需重新登录或移动即可显示出来（参见下文）。

服务端和客户端必须使用相同版本

从 3.1.0-beta-4 版本开始，服务端和每个客户端都必须使用 3.1.0-beta-4 或更高版本。 该版本更改了 LOD 网络协议（v1 -> v2），并且不存在兼容路径：双方用于判断“我是否已经拥有这个区域？”的数字正是为了修复可能导致服务端崩溃的错误而必须更改的内容。

不匹配的双方不会崩溃，也不会卡住。双方都会注意到不匹配，双方都会拒绝，并且双方都会在日志中说明——远距离地形只是不会传输。如果你更新了服务端，请同时更新客户端；如果你更新了客户端，服务端也必须随之更新。

它会在你游戏时保持同步

客户端会向服务端请求一个关于你视野内 LOD 区域的单行摘要——一个计数和一个单一的折叠校验和——然后与其自身的进行比较。如果它们匹配，则不会发生任何操作。如果不匹配，它会拉取区域列表并下载仅有的差异。

这一机制涵盖了双方可能产生差异的所有三种情况：服务端生成了更多地形、你已有的区域发生了变化、或者你丢失了本地磁盘上的区域文件。每次请求消耗 22 字节传出和 34 字节返回，并且服务端在回答时无需读取存储中的任何字节。

键	位置	默认值
sync-interval-seconds	config/chunksmith-lod.properties (客户端)	300

该文件会在客户端首次运行时写入默认值和注释。任何低于 30 的值都会被强制设为 30，这是有意为之：配置值只是一个建议，一秒钟的轮询绝不能变成对已经忙于预生成的服务端的拒绝服务攻击。目前还没有用于此设置的界面。

一个模组，全部搞定

你在做什么	你需要安装什么
单人游戏	Chunksmith。 仅此而已——一直以来都是这样。
在服务器上游玩	服务端和客户端都安装 Chunksmith。 同一个 jar 文件。
运行服务器，仅用于预生成	服务端安装 Chunksmith。 不会加载任何新内容；专用服务端永远不会触及客户端部分。

独立的 Chunksmith-Client 模组已停止维护。 其功能现在已整合到 Chunksmith 中，并且从 3.1.0-beta-4 版本开始，旧的副本将不再有效——它使用 v1 LOD 协议，而 3.1.0-beta-4 版本的服务端会拒绝它并告知原因。无论如何都没有理由保留它，并且你不能同时运行两者：它们会注册相同的网络通道，加载器将拒绝启动并提示你移除其中一个。请删除 Chunksmith-Client；Chunksmith 自己就能完成这项工作。

重新运行会填充缺失的 LOD

在你安装 LOD 渲染器之前已经预生成了世界？只需再次运行相同的预生成任务即可。 Chunksmith 会检查 CSLOD 存储以及世界，逐个区块进行：

磁盘上的情况	Chunksmith 的操作
没有区块	生成它——顺带构建 LOD
有区块，但没有 LOD	加载该区块并从它构建 LOD——不进行世界生成，不重新生成任何内容
有区块并且有 LOD	完全跳过——不加载，不写入

因此，第二次运行只构建缺失的内容，而第三次运行则什么也不做。删除存储的一部分，只有那些部分会被重新构建。任何已完成的操作都不会重做，任何内容都不会被重写。

检查操作是每个区域文件一次小的读取，因此成本微乎其微——对于一个 6,500 区块的选择区域，决定可以跳过哪些内容的耗时不到一毫秒。然后，预生成任务会精确地告诉你它做了什么：生成了多少个区块，从已有区块构建了多少个 LOD，以及因为两者都已存在而跳过了多少个。

强制开启或关闭

config/chunksmith.json 中的 lodEnabled 是一个三态值，而不是一个开关：

lodEnabled	结果
"auto" (默认)	如果加载了 Distant Horizons、Voxy 或 Voxy 分支，则为 开启。在专用服务端上为开启。 否则为关闭。
true	始终开启，无论是否有渲染器。适用于先构建存储，稍后再安装渲染器的情况。
false	始终关闭——即使安装了渲染器也是如此。

明确的 true 或 false 是你的决定，Chunksmith 永远不会覆盖它。无论哪种方式，都会在服务端启动时在日志中声明一次，并且 /cslod status 会再次告诉你当前状态。

开启时的代价：磁盘上每个区块约 ~5.8 KB，预生成速度降低约 16%。使用普通的区域文件——无需原生数据库，无需额外安装任何内容。

LOD 的可用版本

	Distant Horizons	voxy
Fabric	1.20.1, 1.21.1, 1.21.11, 26.1, 26.2, 26.3	1.21.11, 26.1, 26.2, 26.3
NeoForge	1.21.1, 1.21.11, 26.1, 26.2	-
Forge	1.20.1	-

这些是渲染器自身发布的版本——Chunksmith 绝不会声明支持它无法驱动的渲染器。voxy 仅适用于 Fabric（上游未发布 NeoForge 或 Forge 的 jar 文件），并且仅存在于 1.21.11 及 26.x 版本上。Distant Horizons 适用于列表中的所有版本——Chunksmith 需要 DH 2.3.0-b 或更高版本，没有上限。Paper / Spigot / Folia 插件没有 LOD：在该平台上没有客户端渲染器可以传递数据。其余模组版本（1.20.4, 1.20.6, 1.21.4, 1.21.5, 1.21.8, 1.21.10）包含除 LOD 之外的所有功能。

voxy 分支

voxy 经常被分支，因此 Chunksmith 通过一个适配器来为上游 voxy 及其分支提供支持：它会查找模组 ID voxy（每个分支都保留此 ID），读取分支自身的渲染距离设置，并将数据传递给 voxy 自身的摄取 API。没有针对每个分支的代码，也没有需要维护的分支特定列表。

分支是第三方构建的 All-Rights-Reserved 模组。Chunksmith 不发布、镜像、认可或链接任何此类分支——下表仅为测试记录，不包含其他内容。我们在 2026-07-13 运行了实际的 jar 文件并查看了结果：

voxy 构建版本	MC 版本	结果
voxy (上游, MCRcortex)	1.21.11, 26.1.2, 26.2	工作正常。 已检测，读取渲染距离（8192 方块），在单人游戏和多人游戏中均能绘制远距离地形。
mia-edition (ggonzaDNG)	1.21.11	工作正常。 相同，单人游戏和多人游戏均正常。
voxy 26.2 branch (NHblock714)	26.2	工作正常。 单人游戏已验证。
voxy-26.2 (Paulem79)	26.2	工作正常。 已检测，读取距离，LOD 已摄取。
Vulkan-Voxy (SpinGiantCRM)	26.1.2	Chunksmith 端工作正常——已检测，读取距离，LOD 已摄取到其数据库中——但其 Vulkan 渲染器在我们能够测试的两台机器上均未绘制出远距离地形。这是你和该分支之间的问题；Chunksmith 已将数据传递给它。
m-series support (srjefers)	1.21.11	Chunksmith 能正确读取，但该分支本身无法工作。 其渲染器基于一个早于 MC 1.21.9 渲染重制版的旧版 voxy，一旦有任何内容需要绘制，就会抛出 IllegalStateException: Cannot use the default framebuffer —— 即使移除 Chunksmith 也是如此。我们这边无法修复。

如果某个分支更改了 Chunksmith 依赖的某些内容，Chunksmith 会在日志中说明——一次，用简单的语言说明它无法读取什么以及回退到了什么。它绝不会在悄无声息的情况下向你显示更少的地形。

NeoForge 和 Forge：仅限 Distant Horizons

在现代版本上，NeoForge 或 Forge 没有 voxy —— 无论是来自上游还是来自分支。目前所有的“NeoForge voxy”都是通过 Sinytra Connector 加载的 Fabric jar 文件，而 Connector 仅支持 1.20.1 / 1.21 / 1.21.1。没有适用于 1.21.11 或 26.x 的 Connector，因此没有可供重新打包的内容，Chunksmith 也无法提供支持。在 NeoForge 和 Forge 上，Chunksmith 的 LOD 仅适用于 Distant Horizons——这是生态系统的限制，而非 Chunksmith 的限制。

冲突

不要将 Chunksmith 的 LOD 与其他服务端侧的 LOD 提供程序一起运行 — lss、voxyserver 或 lodserver。它们会通过相同的通道注入到相同的渲染器中，先到者获胜；结果将是 LOD 缺失或损坏，而不会出现错误信息。请选择一个。Chunksmith 会将上述三个声明为不兼容，以便你的加载器在你遇到问题之前提前告知你。

使用方法

主命令是 /cs（别名 /chunksmith）；/chunky 和 /cy 是已弃用的别名，会重定向到 /cs。该模组/插件在服务器上需要管理员权限；在 Bukkit 上，它使用 chunksmith.command.* 权限命名空间（旧版 chunky.command.* 仍然有效）。

常见工作流程：

• /cs world <world> - 选择目标世界（默认为当前主世界）
• /cs spawn 或 /cs center <x> <z> - 设置生成中心
• /cs radius <blocks> - 设置半径（或使用 /cs worldborder 来使用世界边界）
• /cs start - 开始生成
• /cs pause / /cs continue - 暂停和恢复（进度会保存）
• /cs cancel 然后 /cs confirm - 停止并丢弃当前/已保存的任务

生成过程会根据服务端刻健康度自动节流，因此可以在玩家在线时运行。

许可

GPL-3.0-only。原始 Chunky (c) pop4959。Chunksmith 修改 (c) Kishku7。