CraftTweaker

[!INFO] Git Commit: 8647048 | Updated: 2026-10-02

CraftTweaker 是 GTNH 1.7.10 的 ZenScript 配方脚本引擎（作者 Stan Hebben），供脚本包在运行时增删配方、改物品属性、注册事件回调与自定义指令。

⚠️ modid 与分类名不一致：本分类的 modid 是 MineTweaker3，不是 CraftTweaker。实测自 src/main/java/minetweaker/mc1710/MineTweakerMod.java:54 的 public static final String MODID = "MineTweaker3"（@Mod 注解在 :51）。CraftTweaker 只是 jar 归档名（gradle.properties 的 customArchiveBaseName = CraftTweaker）与 上游仓库名（github.com/GTNewHorizons/CraftTweaker）。项目在 1.6.4 时代由 CraftTweaker 更名为 MineTweaker，此仓是 GTNewHorizons 维护的 1.7.10 分支；gradle.properties 里 modName = MineTweaker 3、modGroup = minetweaker，而 mcmod.info 用 ${modName} / ${modId} 占位符经构建期替换后写出 MineTweaker3 / MineTweaker 3。脚本、配置文件名、封包频道名一律用 MineTweaker3（如 MineTweaker3.cfg、logs/minetweaker.log）。

源码根：/Users/evlos/a/mirror/CraftTweaker/；包名：minetweaker，1.7.10 专有部分在 minetweaker.mc1710。

核实分支：master（本仓唯一分支，git branch -a 只有 master 与 origin/HEAD、origin/master），浅克隆深度 1，git describe --tags → 3.4.8，该 tag 与 HEAD 同指 8647048。包路径 minetweaker.mc1710 与 gradle.properties 的 minecraftVersion = 1.7.10 一致，无跨版本内容混入（src/main/java/minetweaker 下只有 mc1710 一个版本包），符合 ROADMAP §0.11 对跨版本合并的要求。CHANGELOG-2.1.1.0.md 是 1.x 时代遗留文件，内容仅有标题。

本模组不注册任何方块、物品、实体、TileEntity 或合成配方（registerBlock / registerItem / registerTileEntity / registerEntity / GameRegistry.addRecipe 全仓命中均为 0），也没有 lang 文件。其全部内容就是下表的 API 契约、事件、指令与配置。

维度 内容
modid MineTweaker3（MineTweakerMod.java:54）
名称 MineTweaker 3 / mcmod.info 描述 “Customize your minecraft experience!”
Minecraft 1.7.10（gradle.properties:24、MineTweakerMod.java:55）
Forge 10.13.4.1614（gradle.properties:27）
版本 3.4.8（tag，与 HEAD 同 commit）
作者 Stan Hebben（MineTweakerMod.java:49-50、mcmod.info authorList）
源码规模 286 个 .java（0 .scala、0 .kt）
依赖（自报） ZenScript:1.0.2-GTNH（shadowImplementation，脚本引擎，外部仓）、NotEnoughItems:2.8.93-GTNH:dev（implementation）、industrialcraft-2:2.2.828-experimental:dev（compileOnly）—— 均读自 dependencies.gradle，非从邻近模组推断
方块 / 物品 / 实体 / TileEntity / 配方 0 / 0 / 0 / 0 / 0
指令 1 个（/minetweaker，别名 mt / crafttweaker / ct，仅 OP）
封包 3（全部服务端→客户端）
配置项 6（MineTweaker3.cfg，分 core 2 项 / network 4 项，全部有消费者）
FML 事件入口 6 个 @EventHandler（MineTweakerMod.java）
脚本根作用域符号 16（11 个全局对象 + 5 个内建函数）
@ZenClass / @ZenExpansion / @ZenMethod 89 / 16 / 205
括号处理器 4
条目数 16（4 API / 1 括号 / 3 脚本 / 2 事件 / 1 指令 / 2 配置 / 3 集成）

API 层（api/）

  • 全局符号 - 11 个全局对象 + 5 个内建函数的注册位置，含 3 个不可达的死符号（brewing、minetweaker.IMineTweaker、COLOR_NAMES）
  • 配方与矿物 API - recipes / furnace / oreDict / vanilla 的方法签名与 @Optional 重载折叠规则
  • 类型系统与扩展 - 89 个脚本类型的注解清单、扩展累加 vs 类覆盖的差异、WeightedLiquidStack 重名缺陷
  • Minecraft 层 API - game / IPlayer / IServer / ILoadedMods 运算符，以及 lock() 的 GUI 被注释掉

括号语法（bracket/）

  • 括号语法 - 4 个处理器的完整解析规则：<item:> <liquid:> <ore:> <ic2-item:>，含 meta / 通配符语法与 @BracketHandler(priority) 从未被读取

脚本运行时（script/）

  • 类注册机制 - 构建期用 ASM 扫描 @ZenClass 覆写 MineTweakerRegistry，含 5 个全部不存在的 ClassRegistry 常量
  • 脚本加载与回滚 - .zs / .zip 规则、三级级联（逆序执行）、动作撤销与「卡死」机制
  • 重载生命周期 - reload() 的 10 个步骤、3 个仅 Java 可见的钩子、antiStuck 默认值不一致

事件系统（event/）

  • 玩家事件 - 20 个事件类型中只有 5 个真正触发，其余 15 个仅有接口声明、零 publish 调用
  • 事件管理器可达性 - IEventManager 无 @ZenClass、IEventHandler 脚本名与 Java 类名不同

指令（command/）

  • 指令系统 - /minetweaker 的 OP 门控与分发、两种自定义命令注册、子命令注册不可撤销

配置与网络（setting/）

  • 配置项 - 6 个 boolean 的默认值、分组、逐字段消费者核实；antiStuck 字段初始值是死代码
  • 网络封包 - 3 个封包的 discriminator、方向与门控；桌面操作封包脚本侧不可达

模组集成（integration/）

  • IC2 集成 - 19 个 @ModOnly("IC2") 脚本类（14 台机器 + 作物系统 + 爆炸白名单），51 个 @ZenMethod
  • NEI 集成 - mods.nei.NEI 的 3 个方法；overrideName 继承 OneWayAction 故不可撤销
  • IMC 集成 API - addMineTweakerScript 消息格式、4 个 Java 注册入口、@ModOnly 门控语义

已知实现缺陷汇总

以下均为源码核实，非推测：

缺陷 证据
5 个 ClassRegistry 字符串全部指向不存在的类，MFR / GregTech / Buildcraft 集成无任何代码 MineTweakerMod.java:59-63 vs 逐路径检查 MISSING；MineTweakerAPI.java:289-296 吞异常
brewing 全局符号与字段双双被注释，酿造 API 不可用 MineTweakerAPI.java:62、:108
WeightedLiquidStack 误标为 minetweaker.item.WeightedItemStack，与物品版重名且静默覆盖 api/liquid/WeightedLiquidStack.java:12 vs api/item/WeightedItemStack.java:12；GlobalRegistry.java:94
20 个事件中 15 个从不触发 grep -rn 'events\.publish' 仅 5 处命中；其余 15 个除接口声明外零引用
registerRemover 零调用方，配方删除器列表恒空 GlobalRegistry.java:79-81、MineTweakerAPI.java:343-345
@BracketHandler(priority) 从未被读取 全仓 priority 仅命中注解定义与使用点
lock() 的 GUI 提示被注释，玩家只看到一行日志 MCGame.java:171-175
antiStuck 字段初值 true 与配置默认 false 冲突，初值为死代码 MineTweakerConfig.java:12 vs :42-46
CropsConfig 的 biome 类型校验用 == null，但 Enum.valueOf 抛异常，警告分支不可达 CropsConfig.java:165 附近的守卫
MTEventManager.publishPlayerPickup 有两个重载，XP 版名字应为 publishPlayerPickupXp MTEventManager.java:230-232、:324-326
IEventManager javadoc 自称 37 种事件，实际 20 种，另有 19 种已注释移除 IEventManager.java:5-11、:52-66
@OnRegister 机制完整实现但零使用 grep -rE '^\s*@OnRegister' src/main/java 命中 0
ClassRegistry.getClasses 是空壳，保留仅为不破坏外部引用 ClassRegistry.java:12-15

未能核实的部分

  • ZenScript 语言本身的语法/运算符语义：实现在外部仓 GTNewHorizons/ZenScript，不在本仓。本仓 buildSrc/src/main/java/stanhebben/zenscript/ 只有注解与文档生成器（ZenScriptDoclet 等）副本。
  • events.onPlayerCrafted(...) 等调用在脚本中是否可解析：IEventManager 未经 registerClass 注册，但 ZenScript 对未注册 Java 类型的方法解析策略在外部引擎内，无法在本仓确认。已核实本仓侧事实（无 @ZenClass、无 @ZenMethod），不对最终可用性下结论。