文档可在 ReadTheDocs 网站上查阅。

所有加载器

• JAVA 21+
• Architectury 13.0.8+

Fabric

• Fabric Loader >= 0.16.9
• Fabric API >= 0.110.0+1.21

NeoForge

• NeoForge 21.1.84+

AI 使用声明

这一部分有点长，因为这是我第一次撰写。后续版本的声明应该会短一些。:)

从 1.21.1-0.4.6 开始，我开始使用 AI 辅助模组开发（如果你感兴趣的话，我使用的是 Claude Code Pro）。先介绍一下背景：我是一名拥有近 40 年行业经验的软件工程师（算上高中时期和其他个人项目则接近 50 年），主要从事后端系统开发。我个人认为 AI 在模组开发中可以发挥作用，但难点在于如何“恰当”地运用它，这需要“智慧”和“经验”（注意这里的引号）。此外，不同 AI 模型的工作成果在质量上存在差异，如果用户缺乏软件经验，就有发布低质量作品的风险。遗憾的是，对于这种特殊情况，除了透明地说明我对 AI 的使用之外，我也没有太多别的办法。（我了解关于 AI 的更广泛的讨论和争议。）

如果你对我的 AI 使用经历有建设性的反馈或问题，欢迎在这里评论。

以下是我使用 AI 的详细情况及其对我的模组产生的影响，以便你做出明智的决定。我希望展示的是，AI 除了“帮我生成一个材质”或“做一个像某个模组的模组然后当成自己的作品发布”之外，还可以有其他应用方式。

摘要：

• 代码审查：查找错误、性能问题以及未遵循最佳实践的地方
• 重构：调整代码结构使其可以进行单元测试（隔离、模拟）、删除重复代码、清理配置处理逻辑
• 测试：编写了大量单元测试
• 界面：使模组的界面与 Minecraft 自身界面的工作方式保持一致
• 模组兼容性：分析模组与其他模组的交互方式并加以改进
• 视觉效果：重做了噪声纹理、添加了粒子着色器，并整合了旧版本中基于着色器的极光效果
• 提前规划：规划迁移到 Minecraft 26.2 的路径，使迁移更容易、更不易出错

成果：

测试与可维护性

• 新增 1400 多个单元测试来验证内部逻辑
• 进行重构，消除静态引用，改用注入方式
• 发现重复代码并重构以消除冗余
• 删除了死代码，或实际上没有提供任何价值的代码（例如总是返回 true、没有实际意义贡献等）
• 为需要说明的未加注释的方法补充了注释

性能

• 脚本引擎性能提升了约 40%
  • 修复了区域方块事件扫描器中的性能问题，使其速度提升约 50%
    • 之前存在很多不必要地重复扫描的情况
  • 发现了 Minecraft 的一个生物群系过渡距离行为，并调整区域生物群系扫描器加以利用，将采样数量减少了 85%
  • 提升了瀑布和 RC 蒸汽输出器效果系统的性能和资源占用
  • 在可能的情况下减少了声音效果引擎（混响）的计算量
    • 基本上，只有当任何关键因素发生变化（如玩家所在方块位置、区域内的方块状态变化等）时才会进行计算
  • 添加了一个注解处理器来生成事件循环实现，而不是使用反射（更少的开销，无需分配内存）
    • 这是针对模组内部的事件系统，而非 Architectury/Fabric/NeoForge
  • 修复了界面渲染的性能问题

可靠性

• 修复了缓存未被正确刷新，或数据持有可能超出作用域对象（如实体）引用的边缘情况
• 为可能刷屏日志的重复错误添加了节流机制
• 改进了脚本和 JSON 配置的错误检测与报告
• 模组配置逻辑能够处理手动编辑产生的错误输入，并在配置文件中写入注释
• 提升了 Markdown 解析的健壮性和性能（声音鸣谢对话框）
• 对依赖注入条目进行验证，以便在启动过程的更早阶段检测到循环依赖（这属于开发辅助，而非面向玩家的问题）

功能

• 瀑布水雾与奶泡、萤火虫的光辉与照明，以及极光的回归（参见“新功能”）

新功能

• 新增 /dsversion 命令，可从我的 GitHub 查询版本状态并在本地聊天中报告。回复中将包含可点击的链接，方便你前往各种信息来源。无论登录时的聊天报告是否被禁用，此命令都能正常工作。（一些整合包作者会禁用客户端登录时的聊天报告。）
• 在声音选项对话框中添加了“声音鸣谢”按钮。点击后将显示模组中声音的鸣谢和归属信息。（当你将鼠标悬停在声音配置菜单中的声音上时，这些信息也藏在工具提示中。）
• 人形生物新增了草丛和麦秆踩踏效果（骷髅、僵尸、劫持者等）。抱歉，没有为苦力怕添加此效果。
• 清理了模组配置的处理逻辑
  • 写出配置文件时会为字段添加注释。用户自己的注释将不会被保留。
  • 添加了在加载配置时将现有设置迁移到新字段的机制
• 极光回归了。配置中提供了一组选项，可以启用/禁用极光、调整出现频率以及最大光带数量。
  • 新版本的渲染计算量约为原来的 1/10（不再有电脑取暖器）
  • 站在寒冷/结冰/针叶林生物群系中时，极光会出现在北方天空
  • 新增了极光配置部分，可以在其中启用/禁用极光，并修改其他属性
  • 如果安装了 Iris 或眼球（Oculus），将自动禁用极光。
• 瀑布水雾（取代了相对较新的 Cascade 振动效果）和水流奶泡。
  • 水雾 - 在瀑布落水处底部盘旋（下落的水撞击表面时产生）
  • 奶泡 - 当水从方块上流下或水撞击表面时生成。奶泡会顺着水流方向流动并最终消散。
  • 选项位于配置的瀑布选项部分。（之前的设置（如有）将被迁移。）
  • 如果安装了 Iris 或眼球（Oculus），着色器混合将自动禁用。
• 刷新了萤火虫效果，使其行为更贴近真实的萤火虫；为它们添加了周围的光辉，能略微照亮周围区域。
  • 选项位于萤火虫选项部分。（之前的设置（如有）将被迁移。）
  • 如果安装了 Iris 或眼球（Oculus），着色器照明将自动禁用。
• 扩展了动态环绕的调试 HUD。如果已绑定按键，按下它可以在普通 HUD、玩家所在生物群系信息以及世界中效果系统放置情况之间切换。

更改

• 单个声音配置菜单中的搜索框现在支持使用正则表达式进行过滤
• 将默认混响射线距离从 256 降低到 128
  • 现有配置仍会保持 256（因为新的上限是 256），你可以根据自己的需要降低
  • 数学模型和测试表明，超过 110 的数值对声音的改善微乎其微
• 确保动态环绕的所有脚步声都是单声道，并移除了实时单声道转换支持
• 移除了 Cascade 振动效果，因为它已被水雾和奶泡取代
• 将 26.2 中的迷雾计算器更改向后移植到 1.21.1
  • 生物群系迷雾应该更加柔和
  • 现在会考虑世界迷雾
• 玩家资源包中的配置无论其命名空间是什么都会被读取，这样资源包可以自带声音及其播放配置（例如 dsurround_ex 下的动态环绕扩展）

修复

• 修复了更改世界时（如切换维度）某些缓存未被正确刷新的问题
• 修复了缓存持有对象（如实体）直接引用时间过长的边缘情况
• 修复了与验证和处理来自外部来源的配置数据相关的问题（更好的错误报告等）
• 玩家在水下时，声音效果现在会被正确地抑制
• 混响计算中的部分数学运算存在精度损失，导致声音被略微静音（根据环境不同，约 8 - 20%）
  • 我本人听不出区别，但听起来聆听体验似乎有所改善
• 水下呼吸效果回归（会冒出气泡）
  • 如果呼吸效果被禁用，此功能也会被禁用。
• 修复了加入远程服务器时未检测到标签同步、动态环绕标签缓存未被清空的问题