主题
附录 A 逐模块注意事项与已知缺陷
写 1.12.2 mod 时最容易踩的坑集中在这里。每条都基于源码实现,并标出它影响哪个 API。
通用
- 事件注册要早:所有
Event都是「注册即入队」,触发时才遍历。入口点(init/client-init/server-init)里注册最稳妥;事件没有优先级、没有取消、没有注销。 - 事件不吞异常:监听器抛出的异常会直接向游戏主循环冒泡,请自行 try/catch。
Event的短路语义有坑(core):只有triFunctionFirstNonNull/triFunctionAnyNonNull真正做了filter(Objects::nonNull);其余...First/...Any(包括名字带 NonNull 的两参数版本,实现与不带 NonNull 的完全相同)都不过滤null,一旦被取到的返回值是null,findFirst()/findAny()就会抛NullPointerException。写取值型监听器时要么永远返回非 null,要么改用三参的triFunction*NonNull,要么自己用Event.of实现过滤。
01 core
SimpleIdRegistry/DefaultedIdRegistry/IdBiMap已废弃,请改用registries模块的Registries/WritableRegistry/DefaultedRegistry/IdMap。BlockPos.pack是本模块自定义的位布局(y 取低位),不要与原版BlockPos的长整型表示互换。
04 blockstates
- 在 1.12.2 子工程里,
BlockExtension只有isAir()一个方法;buildStateDefinition之类的钩子只存在于更早版本的子工程。也就是说属性/状态体系在 1.12.2 上没有自动接到Block,需要自己把State映射到 metadata。 libraries/blockstates/README.md里的StatefulBlock示例是旧版用法,对 1.12.2 不适用。
07 branding
- 本模块只作用于文本品牌串(标题界面的版本信息、F3 调试界面的游戏信息),不会修改窗口标题或图标。
08 commands
ArgumentTypes.init()与EntitySelectorOptions.init()在 1.12.2 子工程中没有调用点:参数类型的网络注册表与@e[选项]默认不生效,需要 mod 自己在合适时机调用一次。ItemParser/BlockStateParser的allowTag被硬编码为false(源码留了 TODO),因此#标签语法在 1.12.2 不可用。CommandSourceStack.requestSuggestions直接返回null(源码未说明原因),客户端补全需走ClientPlayNetworkHandlerExtension。
09 config
- 只提供序列化能力,没有自动网络同步:全模块没有
forNetwork()调用点,也不会自己发包。 - JSON 侧没有为
Identifier/BlockPos注册对象序列化器(NBT / 网络侧有),用这两个选项写 JSON 会在序列化时 NPE。 - 没有"配置变更"事件或回调。
13 entrypoints
fabric.mod.json里的键名是字面量init/client-init/server-init(无命名空间前缀)。- 客户端在
Main.main开头调用init→client-init;服务端在MinecraftServer.main开头调用init→server-init。此时游戏实例还不存在。
16 keybinds
Keybind*与KeyBinding*是两代 API,后者已@Deprecated。两者在同一注入点触发(GameOptions构造、load()之前),旧事件先执行。
17 lifecycle-events
- 只有 tick 与世界加载/关闭;没有世界卸载、玩家连接/断开、资源包重载、语言切换事件。需要时只能自己写 mixin 或轮询 tick。
MinecraftInstance.get()/MinecraftServerInstance.get()在实例被清空后会抛IllegalStateException。
19 networking
- 通道名上限 255 字符(原版为 20);负载长度没有任何检查,实际受 Minecraft 自身包长限制。
- 监听器默认在网络线程执行;
ensureOnMainThread()会让 OSL 重投递到主线程并再次调用回调。 - 对端没有安装 OSL 时,
send会静默丢弃(握手阶段交换的通道表里没有该通道)。
20 registries
- 数字 ID 由注册顺序决定,所以必须靠 ID 同步让两端一致;正常使用
blocks/items/biomes/entities时同步已由这些模块代做,一般不必直接碰registry.sync。
21 resource-loader
- 1.12.2 子工程是客户端环境:
ServerResourceLoaderEvents不会触发,server()相关 API 在 1.12.2 没有实际接线。 - 多个同为
required+BOTTOM的资源包之间没有稳定顺序,不要依赖它们之间的相对优先级。
22 text-components
- 没有独立的
Action类型:只有ClickEvent.Action(4 个值)与HoverEvent.Action(只有SHOW_TEXT)。 - 客户端与服务端共用同一份文本模型(不存在"两套同名类"),也没有仅客户端的文本类型。
TextComponents.resolve按"确切运行时类"查找:直接把TextComponent传进去通常只会得到它的toString()。