By

文章目录
  1. 1. 如果你有其它含有Mixin的源代码集
  • 配置MixinGradle
    1. 1. 如果你有其它含有Mixin的源代码集
  • 注解处理器选项
  • 带有选项的mixin闭包示例
  • 如何找到Mixin版本

    • 本文翻译自：Mixins on Minecraft Forge

    Mixin现在作为库与Minecraft Forge一同发布，这意味着不再需要像传统版本那样，将Mixin嵌入到模组Jar中。实际上，这样做会引发问题。

    如混淆与Mixin一章中所述，当你为生产环境构建模组时，某些Mixin功能需要特殊处理才能跨越混淆边界。本指南说明了如何在Forge UserDev环境中使用Mixin功能，以及如何配置构建，以便为Mixin正确生成混淆信息。

    本指南假定你已经创建了一个包（Package）来包含你的Mixin和一个Mixin配置来声明Mixin和选项。

    为了配置要在开发中运行的项目，我们将对build.gradle进行如下更改，并管理混淆：

    • 添加MixinGradle插件。
    • 添加Mixin注解处理器（Annotation Processor）依赖。
    • 通过mixin闭包（Closure）为MixinGradle配置选项。

    在本指南中，将假定你的Mixin配置名为mixins.mymod.json，而refmap被命名为mixins.mymod.refmap.json，并且你只使用了main源代码集（SourceSet）。

    打开你的build.gradle文件并在文件顶部找到plugins块。plugins块已经包含了Forge MDK所需的必要插件。我们将在plugins块的末尾、右花括号之前添加以下行来添加MixinGradle插件：

    1
    id 'org.spongepowered.mixin' version '0.7.+'

    plugins块现在应该如下所示：

    1
    2
    3
    4
    5
    6
    plugins {
        id 'eclipse'
        id 'maven-publish'
        id 'net.minecraftforge.gradle' version '5.1.+'
        id 'org.spongepowered.mixin' version '0.7.+'
    }

    MixinGradle的工作是配置Mixin注解处理器（AP），但是AP不是自动应用的，我们需要将其作为依赖项添加。AP依赖项应该与项目中使用的版本相同或更高（如果不确定使用的是哪个版本的Mixin，请参阅本指南末尾的部分）。

    要将Mixin AP依赖项添加到项目中，请找到该项目的dependencies块。这_不是_Gradle文件顶部buildscript块中的dependencies块，而是文件下面更大的dependencies块。在本指南中，我们假定版本为0.8.5（撰写本文时的当前版本）。

    它当前应该包含minecraft依赖项和一组注释，以及您手动添加的任何其它依赖项。main的AP配置称为annotationProcessor。将Mixin AP依赖项添加到dependencies块：

    1
    2
    3
    4
    5
    6
    dependencies {
        // 指定要使用的Minecraft版本。如果groupId不是'net.minecraft'，则假定该依赖是ForgeGradle的'patcher'依赖，其补丁将被应用。
        // userdev构件是一个特殊名称，会有各种转换应用到它上面。
        minecraft 'net.minecraftforge:forge:1.17.1-37.0.70'
        // 应用 Mixin AP
        annotationProcessor 'org.spongepowered:mixin:0.8.5:processor'

    注意，AP依赖项含有额外的分类词processor。这是一个特殊的臃肿Jar（Fat Jar），其中包含Mixin AP所需的上游依赖项，因此你不必手动指定它们。

    如果你有其它含有Mixin的源代码集

    如果你只有一个源代码集（SourceSet）main，你可以跳过本节。

    额外的源代码集将有相应的Gradle配置，用于定义它们的依赖关系。如果你有其它含有Mixin的源代码集，那么每个源代码集都需要自己的参考映射（Reference Map）（下面将详细介绍），每个源代码集都需要配置Mixin AP依赖项。

    让我们假定你有额外的名为client和api的源代码集。相应的配置名称将是clientAnnotationProcessor和apiAnnotationProcessor，将Mixin AP添加到其中：

    1
    2
    3
    4
    5
    6
    7
    dependencies {
        // 指定要使用的Minecraft版本。如果groupId不是'net.minecraft'，则假定该依赖是ForgeGradle的'patcher'依赖，其补丁将被应用。
        // userdev构件是一个特殊名称，会有各种转换应用到它上面。
        minecraft 'net.minecraftforge:forge:1.17.1-37.0.70'
        annotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
        clientAnnotationProcessor 'org.spongepowered:mixin:0.8.5:processor'
        apiAnnotationProcessor 'org.spongepowered:mixin:0.8.5:processor'

    配置MixinGradle

    MixinGradle提供了一个名为mixin的扩展，允许我们配置插件的选项，MixinGradle然后将这些设置应用到适当的位置。要配置扩展，请指定扩展名和包含我们设置的闭包。这可以放在构建中的任何地方，但我建议将其放在sourceSets或dependencies块之后：

    1
    2
    3
    mixin {
        // MixinGradle 设置
    }

    MixinGradle可以配置AP选项，但我们需要告诉它要为每个编译任务生成的refmap的名称，这必须与配置JSON中的refmap名称相对应。

    请注意，同一源代码集中的配置都应该指定相同的refmap名称，而不管它们包含哪些Mixin。这是因为refmap与SourceSet的compile任务耦合在一起，而不关心你的配置中的Mixin的组织方式。

    我们还可以指定Mixin配置的名称，这将执行两个任务：

    • 配置将被注入到我们所有的运行配置中。
    • 配置名称将添加到所有混淆Jar的Manifest中（在MixinConfigs键中）。

    让我们将main源代码集的refmap名称和配置名称添加到mixin闭包中：

    1
    2
    3
    4
    5
    mixin {
        // MixinGradle 设置
        add sourceSets.main, 'mixins.mymod.refmap.json'
        config 'mixins.mymod.json'
    }

    mixin闭包也可用于配置选项，如Mixin系统属性（用于开发运行）和Mixin注解处理器的选项。例如，我建议在开发期间设置mixin.debug.verbose和mixin.debug.export。为了方便起见，我们可以在mixin闭包中设置这些属性：

    1
    2
    3
    4
    5
    6
    7
    mixin {
        // MixinGradle 设置
        add sourceSets.main, 'mixins.mymod.refmap.json'
        config 'mixins.mymod.json'
        debug.verbose = true
        debug.export = true
    }

    在更改影响运行配置的任何设置后，请记住使用genEclipseRuns，genIntellijRuns或genVSCodeRuns任务重新生成运行配置！

    如果你有其它含有Mixin的源代码集

    如果你只有一个源代码集（SourceSet）main，你可以跳过本节。

    除了Gradle配置，项目中的每一个源代码集都会获得一个对应的Java编译任务，它以源代码集命名。由于每个源代码集都是单独编译的，AP每次都会单独运行，因此每个源代码集都需要一个单独的参考映射（refmap）。基于上面的示例，让我们为client和api源代码集添加refmap名和配置：

    1
    2
    3
    4
    5
    6
    7
    8
    mixin {
        add sourceSets.main, 'mixins.mymod.refmap.json'
        add sourceSets.client, 'mixins.mymod.client.refmap.json'
        add sourceSets.api, 'mixins.mymod.api.refmap.json'
        config 'mixins.mymod.json'
        config 'mixins.mymod.client.json'
        config 'mixins.mymod.api.json'
    }

    注解处理器选项

    MixinGradle使用所有必需的选项配置AP。但是，Mixin AP选项可以通过mixin闭包进行操纵。以下是一些实用选项：

    • boolean disableTargetValidator
      禁用目标验证器（验证Mixin目标是否合理（例如，目标层次结构中存在父类））
    • boolean disableOverwriteChecker
      禁用重写方法检查器，它用来确保@Overwrite方法的JavaDoc含有@author和@reason标记
    • String overwriteErrorLevel
      为重写方法检查器设置错误级别（默认为warning，可以被设置为error）
    • quiet
      抑制来自AP的突出消息和信息输出
    • extraMappings
      指定要提供给AP的附加（自定义）TRSG映射文件的名称，这可用于主映射文件中未指定的映射项
    1
    2
    3
    4
    5
    6
    7
    mixin {
        // AP 设置
        disableTargetValidator = true
        overwriteErrorLevel = 'error'
        quiet
        extraMappings file("my_custom_srgs.tsrg")
    }

    带有选项的mixin闭包示例

    下面是一个完整的例子，展示了当我们配置了所有选项，mixin闭包可能会是什么样子：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    mixin {
        // 每个源代码集的refmap
        add sourceSets.main, 'mixins.mymod.refmap.json'
        // 添加到运行配置和Jar的配置
        config 'mixins.mymod.json'
        // 开发环境运行配置的选项
        debug.verbose = true
        debug.export = true
        dumpTargetOnFailure = true
        // 注解处理器的选项
        quiet
    }

    如何找到Mixin版本

    如果你不确定项目中使用的是哪个版本的Mixin，可以通过以下几种方式找到它：

    1. 在IDE中，检查项目的依赖项列表。例如，在Eclipse中，你可以在Project and External Dependencies容器中查看。

    2. 使用gradle dependencies任务将项目的依赖关系树发送到控制台，并使用find（在Windows上）或grep（在Linux上）对其进行过滤：

      gradlew --console=plain dependencies | find "mixin"

      这应该会向控制台发出几行代码，辨识Mixin依赖版本应该不会太难。

    3. 在开发环境中运行游戏，然后搜索debug.log，查找Mixin子系统版本。
    文章目录
    1. 1. 如果你有其它含有Mixin的源代码集
  • 配置MixinGradle
    1. 1. 如果你有其它含有Mixin的源代码集
  • 注解处理器选项
  • 带有选项的mixin闭包示例
  • 如何找到Mixin版本