NSUK:作物API

NSUK:作物API

New: Sim-U-Kraft 农田盒子的共享作物注册表与工作流程。

NSUK:作物 API 为《New: Sim-U-Kraft》的农田盒提供统一的作物注册表与作业流程。 本模组是前置库,不是内容模组。它自己不添加任何方块、物品或作物。它的职责是让多个作物附属共用同一个农田盒,而不必每个附属都自带一套 Mixin、界面和存档格式。

它解决什么问题

《New: Sim-U-Kraft》会雇佣公民去经营农田盒。原版农田盒只认固定的几种作物。任何想让农民种别的作物的附属,都必须接住同样的五个作业阶段:浇水、翻地、播种、骨粉、收割。如果两个附属各自去接,通常后加载的那个覆盖先加载的,另一个附属的作物就会卡住不动。

本 API 用一个注册表替代这种竞争:

  • 一张注册表。 附属在 FMLCommonSetupEvent 里调用 CropRegistry.register(...),用 CropSpec 描述作物:编号、种子物品、图标、作物方块、显示名、来源模组、分组名、作业策略。
  • 一套作业流程。 宿主那五个阶段的钩子由本 API 统一应答。只想种普通耕地作物的附属完全不必自己写作业类。
  • 一个选择界面。 作物选择界面支持中英文搜索,按来源模组分组,分组可折叠,原版作物单独成组。
  • 一种存档写法。 农田盒只存一个作物编号。编号是稳定字符串,所以更新前选好作物的盒子在更新后照常运行。
  • 共存仲裁。 多个附属声明同一种作物时,由 API 判定归属,而不是交给加载顺序。

配置

配置文件位于 config/nsukcropapi-common.toml。

  • autoDiscovery:默认 false。开启后,API 会扫描已加载模组里没有 JSON 定义的 CropBlock,把它们也加进农田盒。默认关闭的原因是:扫描出来的作物只能按方块反推种子与产物,结果可能与玩家预期不符。
  • disabledSources:被关闭的来源模组 id 列表。通常通过游戏内界面修改,不建议手改文件。

游戏内界面名为 NSUK 作物设置,从模组列表的 Config 按钮进入。关闭某个来源只会把它从选择界面里移除;已经种着该作物的农田盒仍会继续运行,因此不会损坏既有存档。

命令

/nsukcrop farmland <作物编号>

需要权限等级 2。把准星对准 8 格内的农田盒后执行,可直接设定该盒的作物。这是选择界面打不开时的兜底手段,例如盒子由命令方块或脚本放置。

给附属开发者

// 在 FMLCommonSetupEvent 中调用
CropRegistry.register(new CropSpec(
    "mymod_tomato",          // 存进农田盒的编号
    MY_TOMATO_SEEDS,         // 从箱子消耗的种子
    MY_TOMATO_SEEDS,         // 界面图标
    MY_TOMATO_CROP,          // 作物方块
    "block.mymod.tomato",    // 翻译键
    "mymod",                 // 来源模组 id(界面分组用)
    "gui.mymod.group",       // 分组标题键
    CropWork.PLAIN           // 作业策略;null 表示按普通耕地处理
));

纯数据附属可以完全不写 Java。把作物 JSON 放进 data/<你的模组 id>/<目录>/,然后调用:

CropAddons.bootstrap(MyMod.class, "mymod", "crops");

加载器会解析该目录下的每个 JSON 文件,所以以后新增作物只需丢一个文件,不必改代码。若某种作物的种子或作物方块在注册表里找不到,加载器会跳过它并在日志里留下警告,而不会让游戏崩溃。

前置要求

  • Minecraft 1.21.1
  • NeoForge 21.1.228 或更新,低于 21.2
  • 《New: Sim-U-Kraft》2.0.0 或更新(必需)

API 本身不提供任何作物。至少要装一个附属,选择界面里才会有内容。

安装

  1. 为 Minecraft 1.21.1 安装 NeoForge 21.1.228 或更新版本。
  2. 把《New: Sim-U-Kraft》和本 jar 放进 mods 文件夹。
  3. 再放入一个或多个作物附属。
  4. 启动一次游戏,让配置文件生成。

本模组需要在客户端与服务端同时安装。只装在服务端不会崩溃,但客户端不会有选择界面。

兼容性说明

  • 本模组不改写宿主的作物列表,只往里注册。因此移除一个附属,只会移除该附属的条目。
  • 如果在农田盒种着某附属作物时移除该附属,盒子会指向一个已不存在的编号并停下等待。重新选一种已注册的作物即可恢复。
  • 直接钩同样五个阶段的第三方模组仍可能冲突。遇到这类问题请报告模组组合,不要假设本 API 能仲裁第三方的 Mixin。

许可

GPL-3.0。源码与问题追踪地址由作者提供。