Chunky Pregenerator

Chunky Pregenerator

一款适用于 Minecraft 1.21.11 的 Fabric 模组，使用 Chunky 作为生成后端，自动为玩家预生成周围区块。完全在后台运行，即使在螺旋生成过程中重启也能继续，并支持单人游戏和专用服务器。

使用 Claude 氛围编程。采用 MIT 许可证。没错，它打磨得极其完善，Bug 也少之又少。 

为何选择它，而不是 Distant Horizons 内置的预生成器

DH 的预生成器只会以世界中心为圆心、按固定半径运行一次。它不会追踪玩家实际去过的地方，无法随玩家移动调整，也不知道应该优先生成附近地形而非远处地形；服务器负载吃紧时，它也无法暂停。启动之后，就没有然后了。

本模组以玩家的实际位置为中心，按不断扩大的螺旋环生成区块。离玩家最近的地形始终优先生成。当玩家离上次生成中心足够远时，会自动启动新一批生成，并以玩家的新位置为中心。如果生成期间服务器 TPS 大幅下降，就会通知 Chunky 暂停，等待性能恢复。恢复后，生成会从暂停处继续。如果你在螺旋生成过程中退出，模组会准确保存当前所在的环；重新加入后便从那里继续。Chunky 会自动跳过每个环内已生成的区块，因此最多只会损失当前环尚未完成的部分。

每批生成开始时，本模组还会短暂调高再调低渲染距离，强制 Voxy 重建 LOD。否则，Voxy 不会将新预生成的地形识别为 LOD 数据，除非有其他操作触发重建。

功能

螺旋批次生成 — 每批生成会按二次缓入曲线拆分为同心环。玩家附近的环间距更小，越向外间距越大，符合实际探索方式。Chunky 会自动跳过每个环内已生成的区块，因此重叠的环基本不会增加额外开销。

根据移动重新设定中心 — 玩家离上次生成中心超过死区距离后，会自动以玩家的新位置为中心启动新一批生成。默认死区为生成半径的一半，因此玩家前进方向始终有一段预生成地形作为缓冲。

重新加入后恢复当前批次 — 每次保存时，环索引、环列表和中心位置都会写入世界的数据文件夹。重新加入后，经过加入延迟，模组会重新启动当前环的生成。Chunky 会自动跳过已完成的部分。

TPS 自动暂停 — 服务器 TPS 低于阈值（默认 15 TPS）时，Chunky 会暂停；TPS 恢复（默认 18 TPS）后则会继续运行。避免生成过程进一步加剧性能问题。

Voxy LOD 集成 — 启用后，生成半径和死区会跟随 Voxy 的实际渲染距离设置，而非使用静态配置值。模组会通过反射实时读取 Voxy 配置；如果反射失败，则改用 JSON 解析。每批生成开始时还会触发 Voxy LOD 重建（先调高再调低渲染距离），让新生成的地形无需等待即可显示在 LOD 中。

轮询 Chunky API — 完成状态检测会通过反射调用 Chunky 实际的 `ChunkyAPI.isRunning()`，而不是依赖日志解析或计时器。Chunky 实际完成后会立即推进到下一环。推进前要求连续两次读取结果均为 false，以消除新任务刚启动时短暂窗口期带来的误判。

卡滞监控 — 如果 Chunky 连续 10 分钟完全没有活动（`isRunning()` 始终没有返回 true），监控程序就会重置状态，避免任务永久挂起。它统计的是实际卡滞时间，而非总运行时长，因此合法的数小时生成任务不会误触发。

每次会话的进度播报 — Chunky 每秒刷屏的日志会被抑制，改为按可配置的时间间隔发送简洁的进度摘要。

下界自动缩放 — 下界的生成半径会自动除以 8，以匹配坐标比例。主世界 250 区块的半径在下界中约为 31 区块。

末地门槛 — 玩家实际进入末地之前，不会预生成末地。首次进入时，末地传送门会生成末影龙；你肯定不希望它在预生成期间悄无声息地出现。

Sodium 设置界面 — 所有设置都集中显示在 Sodium 视频设置的专属页面中，并提供实时提示，显示 Voxy 实际读取到的渲染距离。

服务器与单人游戏 — 支持专用服务器和单人游戏的集成服务器。客户端模组（Sodium、Voxy）为可选项。

前置要求
依赖项 必需 备注
Fabric Loader 是 0.19.3+
Fabric API 是 任意 1.21.11 版本
Chunky 是 1.4.55+
Sodium 客户端 游戏内设置界面 + LOD 重建周期
Voxy 可选 允许使用 Voxy 的渲染距离驱动生成半径
单人游戏中建议将 Chunky-Offline 与 Chunky 配合使用。它可以让 Chunky 在世界加载间隔期间继续运行。

如果没有 Voxy，此模组会使用配置中的静态 generationRadius 和 triggerDistance。

安装

将 jar 文件放入 mods/ 文件夹。首次启动时会在 config/chunkypregen.json 生成配置文件。如果已安装 Sodium，所有设置都可在 选项 > 视频设置 > Chunky Pregenerator 中找到。使用 /chunkypregen reload 可在游戏内重新加载配置。

命令
/chunkypregen status 显示各维度状态、当前环、上次中心位置和实时进度
/chunkypregen trigger 手动为所有已启用的维度启动一组生成任务
/chunkypregen trigger 为指定维度启动任务
/chunkypregen cancel 取消所有正在运行的 Chunky 任务并重置状态
/chunkypregen reset 清除已保存的上次中心位置
/chunkypregen stats 会话统计：已启动任务数、预计区块数、运行时间
/chunkypregen config 在聊天栏中显示当前配置
/chunkypregen debug 切换调试日志
/chunkypregen reload 无需重启即可从磁盘重新加载配置
/chunkypregen setworld reset 清除新世界初始化标记，以便再次触发首次加入时的预生成

螺旋曲线的工作原理
环的半径按 radius x ((i+1)/N)^2 计算。环数 N 会根据半径和 generationRingStep 自动缩放。默认步长为 25 时，半径为 250 区块会生成 13 个环；半径为 1000 区块时会生成 20 个环。每个环依次启动，只有在 isRunning() 确认当前环已完成后，才会开始下一个环。

二次曲线意味着第 1 环覆盖最内侧约 1% 的区域，越外侧的环覆盖范围越大。玩家附近的区域总是最先完成。

许可证
MIT