MixinTale

MixinTale

Hytale 模组的字节码补丁框架。 模组作者只需编写一个普通的静态 Java 方法并加上注解，MixinTale 就会在他们指定的游戏类内部运行它——甚至早于 JVM 定义该类的时刻。

如果你是因为某个模组提示而来到这里：下载它，放进 EarlyPlugins，就完成了。本页其余内容是写给模组作者的。

---

面向玩家和服务器管理员

MixinTale 是一个核心框架，而不是玩法模组。单独安装它不会改变任何东西。那些会修补游戏的模组会把它列为前置依赖。

安装

单人游戏	将 MixinTale-Bootstrap-3.0.0.jar 放入 [GameFolder]/UserData/EarlyPlugins/
专用服务器	将其放入 [ServerFolder]/earlyplugins/

然后像往常一样，将需要它的模组安装到 UserData/Mods/（单人游戏）或 Mods/（服务器）。

专用服务器还必须以 --accept-early-plugins 启动。 自 0.6.3 起，类转换器需要显式启用，没有连接控制台的服务器会拒绝启动，而不是静默加载它们。单人游戏会自动接受它们。

检查是否生效

日志开头应出现：

[EarlyPlugin] Loading transformer: com.traktool.mixintale.bootstrap.MixinTaleTransformer (priority=1000)
[MixinTale/INFO] MixinTale 3.0.0 ready - 1 patch(es) across 1 class(es) from 1 archive(s).

如果显示 0 patch(es)，说明 MixinTale 已启动但没有找到任何要处理的内容。几乎总是以下情况之一：

• 模组 jar 不在服务器扫描的文件夹中，或者
• 该模组在该世界的 config.json 中处于关闭状态。每个存档都有一个 Mods 块；如果某个模组带有 "Enabled": false，它会在启动时被跳过，日志中也会说明。将其设为 true。

要求

Hytale 0.6.3 或更高版本。无需自行安装 Java——游戏自带运行时。

卸载

删除该 jar 即可。依赖它的模组会正常加载，并在日志中说明其补丁未应用。

这安全吗？

它会在 JVM 看到游戏自身的字节码之前对其进行重写，Hytale 会就此显示警告横幅。该警告是准确的，你应该阅读它。MixinTale 的行为是可审查的：使用 -Dmixintale.report=mixintale-report.txt 启动会精确写出每个已安装模组修改了哪个类的哪个方法。不会向任何地方发送数据，运行时不会下载任何内容，也没有遥测。

---

面向模组作者

@Patch(RepairItemInteraction.class)
public final class RepairPenaltyPatch {

    @RedirectCall(value = "run", target = Item.class, name = "getMaxDurability")
    public static double noPenaltyBase(@This Item item) {
        return 0.0D;
    }
}

这就是一个完整、可发布的模组——它正是 NoRepairDurabilityPenalty 2.0.0 的全部内容。无需 JVM 描述符，无需 refmap，无需配置文件，类路径上也无需运行时库。

可用的功能

@Prefix	最先运行；返回 false 会跳过原方法体，并可提供结果
@Postfix	在每个 return 处运行；可以重写返回值
@Replace	替换方法体
@RedirectCall	按序号拦截方法内某个特定的调用
@Accessor	读写目标的私有字段
@Invoker	调用目标的私有方法

参数通过 @This、@Arg(n) 和 @Result 绑定。**你几乎永远不需要编写描述符：**注解处理器会根据处理器的参数类型推断目标的签名，并在无法推断时于编译期告知你——方法名写错是构建错误，而不是运行时静默无操作。

如何避免出问题

MixinTale 绝不会生成引用你的模组的字节码。你的处理器会被移入目标类：所有对补丁类的引用都会被重写为目标类，每个成员都会在按补丁生成的命名前缀下重命名，例如 mixintale$3f9c1a2b$noPenaltyBase。

这同时带来三个好处——处理器可以访问私有状态，不会跨越类加载器边界（因此不会出现 NoClassDefFoundError），并且两个修补同一个类的模组不会发生冲突。代价是有一条规则：**处理器只能提及 JDK 类型、com.hypixel.hytale.* 类型以及其自身补丁类的成员。**处理器会在编译时强制执行这一规则。

入门

安装 MixinTale — Developer Tools（API jar 和注解处理器）并阅读手册：

https://github.com/Traktool/MixinTale

手册涵盖每个原语的完整示例、签名推断、如何对补丁进行条件控制以免对所有玩家改变游戏、两个模组命中同一方法时的优先级、运行时开关，以及游戏更新破坏补丁时该怎么办。

在动手之前

官方 0.6.x API 非常庞大——133 种事件类型、ECS 系统注册、资源包、命令、注册表。**如果你的模组能通过事件或注册表实现，就改用那些。**补丁是维护负担；事件订阅不是。MixinTale 适用于官方 API 触及不到的地方：伤害、死亡、掉落、耐久、特定交互，以及任何必须替换原版逻辑而非与其并行运行的内容。