Fabric Wiki

User Tools

Site Tools

Trace: • 网络通信 • Fabric 教程 • 端
zh_cn:documentation:fabric_loom

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
zh_cn:documentation:fabric_loom [2022/03/19 14:24] – created solidblockzh_cn:documentation:fabric_loom [2023/10/10 15:33] (current) – Sync rawdiamondmc
Line 1: Line 1:
 ====== Fabric Loom ====== ====== Fabric Loom ======
  
-Fabric Loom，或者简称为 Loom，是个 [[https://gradle.org/|Gradle]] 插件，用于 Fabric 生态系统的模组开发中。Loom 提供了在开发环境中安装 Minecraft 和模组的一系列工具，所以你可以针对 Minecraft 混淆及其发行版和版本之间的差异来将 Loom 与 Minecraft 链接起来。Loom 还提供了用于 Fabric 加载器的运行配置、mixin 编译处理，以及用于 Fabric Loader 的 jar 中 jar 系统的工具。+Fabric Loom，或者简称为 Loom，是个 [[https://gradle.org/|Gradle]] 插件，用于 Fabric 生态系统的模组开发中。Loom 提供了在开发环境中安装 Minecraft 和模组的一系列工具，所以你可以针对 Minecraft 混淆及其发行版和版本之间的差异来将 Loom 与 Minecraft 链接起来。Loom 还提供了用于 Fabric 加载器的运行配置、mixin 编译处理，以及用于 Fabric Loader 的 jar-in-jar 系统的工具。
  
 ==== 常用任务 ==== ==== 常用任务 ====
  
   * ''migrateMappings''：将当前源代码合并到指定的映射中。见 [[zh_cn:tutorial:migratemappings]]。   * ''migrateMappings''：将当前源代码合并到指定的映射中。见 [[zh_cn:tutorial:migratemappings]]。
-  * ''remapJar''：产生包含 ''jar'' 任务的重映射的输出的 jar。同时也会将 jar 中 jar 包含在模组中。运行 ''build'' 时会调用。+  * ''remapJar''：产生包含 ''jar'' 任务的重映射的输出的 jar。同时也会将 jar-in-jar 包含在模组中。运行 ''build'' 时会调用。
   * ''genSources''：使用默认的反编译器（CFR）反编译 Minecraft jar。   * ''genSources''：使用默认的反编译器（CFR）反编译 Minecraft jar。
   * ''downloadAssets''：下载配置的 Minecraft 版本的资源索引和对象，下载到用户缓存中。   * ''downloadAssets''：下载配置的 Minecraft 版本的资源索引和对象，下载到用户缓存中。
   * ''genEclipseRuns''：安装 Eclipse 运行配置并创建运行目录（如果还不存在）。   * ''genEclipseRuns''：安装 Eclipse 运行配置并创建运行目录（如果还不存在）。
   * ''vscode''：生成或覆盖 Visual Studio Code 的 ''launch.json'' 文件，启动配置在 ''.vscode'' 文件夹中，并创建运行目录，如果还不存在。   * ''vscode''：生成或覆盖 Visual Studio Code 的 ''launch.json'' 文件，启动配置在 ''.vscode'' 文件夹中，并创建运行目录，如果还不存在。
 +  * ''ideaSyncTask''：生成（但是不会覆盖）Intellij IDEA 的启动配置，包括客户端和服务器。
   * ''remapSourcesJar''：只有在 AbstractArchiveTask ''sourcesJar'' 存在时存在。将 ''sourcesJar'' 任务的输出重映射。   * ''remapSourcesJar''：只有在 AbstractArchiveTask ''sourcesJar'' 存在时存在。将 ''sourcesJar'' 任务的输出重映射。
   * ''runClient''：将 Fabric Loader 作为 Minecraft 客户端运行的 JavaExec 任务。   * ''runClient''：将 Fabric Loader 作为 Minecraft 客户端运行的 JavaExec 任务。
Line 21: Line 22:
 <code> <code>
 dependencies { dependencies {
- implementation project(path: ":name", configuration: "namedElements")+    implementation project(path: ":name", configuration: "namedElements")
 } }
 </code> </code>
 +
 +如果你在多项目构建中使用分离源集，你还需要为其他项目客户端源集添加依赖项。
 +
 +<code>
 +dependencies {
 +    clientImplementation project(":name").sourceSets.client.output
 +}
 +</code>
 +
 +==== 分离客户端与常规代码 ====
 +
 +多年来，服务器崩溃往往是因为安装在服务器上时意外调用客户端代码。最新的 loom 和 loader 版本提供了一个选项，要求将所有客户端代码移动到其自己的源集中。这样做是为了提供编译时的保证，以防止在服务器上调用仅限客户端的 Minecraft 代码或仅限客户端的 API。在客户端和服务器上都可以使用的单个 jar 文件仍然是从两个源集构建的。
 +
 +以下 build.gradle 文件片段展示了如何为您的模组启用此功能。由于您的模组现在将拆分为两个源集，因此您将需要使用新的 DSL 来定义您的模组源集。这将会让 Fabric Loader 将您的模组类路径组合在一起，对于其他一些复杂的多项目设置也有用。
 +
 +要分享客户端与服务器的代码，需要 Minecraft 1.18（建议 1.19）、Loader 0.14 和 Loom 1.0 以上的版本。
 +<code>
 +loom {
 + splitEnvironmentSourceSets()
 +
 + mods {
 +        modid {
 +            sourceSet sourceSets.main
 +            sourceSet sourceSets.client
 +        }
 + }
 + }
 +</code>
 +
 +==== 多项目优化 ====
 +
 +如果你的 Gradle 项目有多个子项目并使用相同的 Minecraft 版本，如 Fabric API，从 Loom 1.1 开始，你可以选择使用高级的优化。在 gradle.properties 中加入 <code>fabric.loom.multiProjectOptimisation=true</code>从而减少构建时间和内存使用，因为会在重映射多个输出的 jar 时在项目之间共享 Tiny Remapper 实例。
  
 ==== 选项 ==== ==== 选项 ====
Line 95: Line 128:
  // 用于配置 mixin 选项，或应用到额外的源集。  // 用于配置 mixin 选项，或应用到额外的源集。
  mixin {  mixin {
- // When disabled tiny remapper will be used to remap Mixins instead of the AP. Experimental.+ // 若禁用，会使用 tiny remapper 来重映射 Mixin 而非 AP。实验性。
  useLegacyMixinAp = true  useLegacyMixinAp = true
- // Set the default refmap name+ // 设置默认的 refmap 名称
  defaultRefmapName = "example.refmap.json"  defaultRefmapName = "example.refmap.json"
  
- // See https://github.com/FabricMC/fabric-loom/blob/dev/0.11/src/main/java/net/fabricmc/loom/api/MixinExtensionAPI.java for options to add additional sourcesets+ // 关于添加额外资源集的选项，参见 https://github.com/FabricMC/fabric-loom/blob/dev/0.11/src/main/java/net/fabricmc/loom/api/MixinExtensionAPI.java
  }  }
  
Line 121: Line 154:
  // 若启用，将会应用配置的注入的接口。  // 若启用，将会应用配置的注入的接口。
  enableDependencyInterfaceInjection = true  enableDependencyInterfaceInjection = true
 + }
 +
 + // 将 Minecraft jar 和传入的依赖项拆分到 main（common）和仅限客户端的源集。
 + // 这可以在编译期间就确保访问仅限客户端的代码时的安全。
 + splitEnvironmentSourceSets()
 +
 + // 这个 mods 语句块用于将由多个类路径的项组合在一起。
 + mods {
 + modid {
 + // 使用分离的资源时，你应该添加 main 和 common 源集
 + sourceSet sourceSets.main
 + sourceSet sourceSets.client
 + }
  }  }
 } }
  
 remapJar { remapJar {
- // Set the input jar for the task, also valid for remapSourcesJar+ // 设置任务的输出 jar，同样对 remapSourcesJar 有效
  inputFile = file("example.jar")  inputFile = file("example.jar")
- // Set the source namespace, also valid for remapSourcesJar+ // 设置资源命名空间，同样对 remapSourcesJar 有效
  sourceNamespace = "named"  sourceNamespace = "named"
- // Set the target namespace, also valid for remapSourcesJar+ // 设置目标命名空间，同样对 remapSourcesJar 有效
  targetNamespace = "intermediary"  targetNamespace = "intermediary"
- // Add additional jar files to the remap classpath, also valid for remapSourcesJar+ // 给重映射类路径添加额外的 jar，同样对 remapSourcesJar 有效
  classpath.from file("classpath.jar")  classpath.from file("classpath.jar")
  
- // Add a nested mod jar to this task, the include configuration should be used for maven libraries and mods.+ // 将嵌套的模组 jar 添加到该任务，include 配置应该用于 maven 库和模组。
  nestedJars.from file("nested.jar")  nestedJars.from file("nested.jar")
- // When enabled nested jars will be included with the output jar.+ // 若启用，输出的 jar 中会包含嵌套的 jar。
  addNestedDependencies = true  addNestedDependencies = true
 } }
  
 dependencies { dependencies {
- // Set the minecraft version.+ // 设置 Minecraft 版本。
  minecraft "com.mojang:minecraft:1.18.1"  minecraft "com.mojang:minecraft:1.18.1"
  
- // Use mappings from maven.+ // 使用 maven 中的映射。
  mappings "net.fabricmc:yarn:1.18.1+build.22:v2"  mappings "net.fabricmc:yarn:1.18.1+build.22:v2"
  
- // Use the offical mojang mappings+ // 使用官方 mojang 映射
  mappings loom.officialMojangMappings()  mappings loom.officialMojangMappings()
  
- // Layered mappings using official mojang mappings and parchment.+ // 使用官方 mojang 映射和 parchment 的分层映射。
  mappings loom.layered() {  mappings loom.layered() {
  officialMojangMappings()  officialMojangMappings()
- // Use parchment mappings. NOTE: Parchment maven must be manually added. (https://maven.parchmentmc.org)+ // 使用 parchment 映射。注意：必须手动添加 Parchment maven（https://maven.parchmentmc.org）
  parchment("org.parchmentmc.data:parchment-1.17.1:2021.09.05@zip")  parchment("org.parchmentmc.data:parchment-1.17.1:2021.09.05@zip")
  }  }
  
- // Remap a mod from maven and apply to gradle's implementation configuration + // 从 maven 中重映射一个模组，并应用到 gradle 的 implementation 配置 
- // (Minor detail: it's not exactly applied *to* the configuration, but a clone of it intended for mod dependencies)+ // （小的细节：不会准确地应用*到*配置，但是会克隆一份以用于模组依赖）
  modImplementation "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"  modImplementation "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"
  
- // Remap a mod from maven and apply to gradle's api configuration+ // 从 maven 中重映射一个模组，并应用到 gradle 的 api 配置
  modApi "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"  modApi "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"
  
- // Remap a mod from maven and apply to gradle's compileOnly configuration+ // 从 maven 中重映射一个模组，并应用到 gradle 的 compileOnly 配置
  modCompileOnly "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"  modCompileOnly "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"
  
- // Remap a mod from maven and apply to gradle's compileOnlyApi configuration+ // 从 maven 中重映射一个模组，并应用到 gradle 的 compileOnlyApi 配置
  modCompileOnlyApi "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"  modCompileOnlyApi "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"
  
- // Remap a mod from maven and apply to gradle's runtimeOnly configuration+ // 从 maven 中重映射一个模组，并应用到 gradle 的 runtimeOnly配置
  modRuntimeOnly "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"  modRuntimeOnly "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"
  
- // Remap a mod from maven and apply to loom's localRuntime configuration. + // 从 maven 中重映射一个模组，并应用到 loom 的 localRuntime 配置。 
- // Behaves like runtimeOnly but is not exposed in to dependents. A bit like testRuntimeOnly but for mods.+ // 和 runtimeOnly 的做法类似，但是不会暴露到依赖项中。有点像 testRuntimeOnly，不过是对于模组的。
  modLocalRuntime "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"  modLocalRuntime "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"
  
- // Include a mod jar in the remapped jar. None transitive.+ // 在重映射的 jar 中包含一个模组 jar。不可传递。
  include "example:example-mod:1.1.1"  include "example:example-mod:1.1.1"
  
- // Include a none mod library jar in the remapped jar. A dummy mod will be generated. None transitive.+ // 在重映射的 jar 中包含一个空模组库。会生成空模组。不可传递。
  include "example:example-lib:1.1.1"  include "example:example-lib:1.1.1"
  
- // Helper to aid with depending on a specific fabric api version.+ // 根据特定的结构 api 版本提供帮助的助手。
  modImplementation fabricApi.module("fabric-api-base", "0.46.2+1.18")  modImplementation fabricApi.module("fabric-api-base", "0.46.2+1.18")
  
- // Depend on a loom sub project by using the namedElements configuration.+ // 使用 namedElements 配置，依赖一个 loom 子项目。
  implementation project(path: ":name", configuration: "namedElements")  implementation project(path: ":name", configuration: "namedElements")
 } }
Line 199: Line 245:
 Loom 旨在通过简单地在用户选择的 IDE 中设置工作区来开箱即用，因此背后做了很多事以创建带有 Minecraft 的开发环境： Loom 旨在通过简单地在用户选择的 IDE 中设置工作区来开箱即用，因此背后做了很多事以创建带有 Minecraft 的开发环境：
  
-  - Downloads the client and server jar from official channels for the configured version of Minecraft. +  - 从官方渠道下载指定版本 Minecraft 的客户端和服务器 jar。 
-  - Merges the client and server jar to produce a merged jar with ''@Environment'' and ''@EnvironmentInterface'' annotations. +  - 将客户端和服务器 jar 合并到一起以生成一个合并的 jar，并加上 ''@Environment'' 和 ''@EnvironmentInterface'' 注解。 
-  - Downloads the configured mappings. +  - 下载配置的映射。 
-  - Remaps the merged jar with intermediary mappings to produce an intermediary jar. +  - 使用中间映射重映射合并的 jar 产生一个中间 jar。 
-  - Remaps the merged jar with yarn mappings to produce a mapped jar. +  - 使用 yarn 映射重映射合并的 jar 产生一个映射的 jar。 
-  - Optional: Decompiles the mapped jar to produce a mapped sources jar and linemap, and applies the linemap to the mapped jar. +  - 可选的：反编译映射了的 jar，产生一个映射的源 jar 和行映射，并将行映射应用到合并的 jar。 
-  - Adds dependencies of Minecraft. +  - 添加 Minecraft 的依赖。 
-  - Downloads Minecraft assets. +  - 下载 Minecraft 资源文件（assets）。 
-  - Processes and includes mod-augmented dependencies (and optionally extracts and remaps nested JARs).+  - 处理并包含模组增强的依赖（还可以导出并重映射嵌套的 JAR）。
  
 ==== 缓存 ==== ==== 缓存 ====
  
-  * ''${GRADLE_HOME}/caches/fabric-loom'': The user cache, a cache shared by all Loom projects for a user. Used to cache Minecraft assets, jars, merged jars, intermediary jars and mapped jars. +  * ''${GRADLE_HOME}/caches/fabric-loom''：用户缓存，用户所有 Loom 项目共用的缓存。用来缓存 Minecraft 资源文件（assets）、jars、合并的 jars、中间 jars 和映射的 jars。 
-  * ''.gradle/loom-cache'': The root project persistent cache, a cache shared by a project and its subprojects. Used to cache remapped mods as well as generated included mod JARs. +  * ''.gradle/loom-cache''：根项目持久缓存，项目和子项目共用的缓存。用来缓存重映射的模组以及生成的包含的模组 JAR。 
-  * ''build/loom-cache'': The root project build cache. +  * ''build/loom-cache''：根项目构建缓存。 
-  * ''**/build/loom-cache'': The (sub)project build cache. +  * ''**/build/loom-cache''：项目和子项目的构建缓存。
 ==== 依赖配置 ==== ==== 依赖配置 ====
  
-  * ''minecraft'': Defines the version of Minecraft to be used in the development environment.  +  * ''minecraft''：定义用于开发环境的 Minecraft 版本。 
-  * ''mappings'': Defines the mappings to be used in the development environment. +  * ''mappings''：定义用于开发环境的映射。 
-  * ''modCompile'', ''modImplementation'', ''modApi'' and ''modRuntime'': Augmented variants of ''compile'', ''implementation'', ''api'' and ''runtime'' for mod dependencies. Will be remapped to match the mappings in the development environment and has any nested JARs removed. Nested JARs can optionally be extracted and remapped. +  * ''modCompile''、''modImplementation''、''modApi'' 和''modRuntime''：相当于''compile''、''implementation''、''api''和''runtime''的增强型变种，用于模组依赖。会被重映射以对应开发环境，并且会移除嵌套的 JAR。可以选择导出并重映射嵌套的 JAR。 
-  * ''include'': Declares a dependency that should be included as a jar-in-jar in the ''remapJar'' output. This dependency configuration is not transitive. For non-mod dependencies, Loom will generate a mod JAR with a fabric.mod.json using the name as the mod ID and the same version.+  * ''include''：生命一个应在 ''remapJar'' 输出中包含的 jar-in-jar 依赖。该依赖配置是不可传递的。对于非模组依赖，Loom 会生成一个模组 JAR，其中 fabric.mod.json 使用模组 ID 的名称和相同版本。
  
 ==== 默认配置 ==== ==== 默认配置 ====
  
-  * Applies the following plugins: ''java'', ''eclipse'' and ''idea''. +  * 应用以下插件：''java''、''eclipse'' 和 ''idea''。 
-  * Adds the following Maven repositories: Fabric [[https://maven.fabricmc.net/]], Mojang [[https://libraries.minecraft.net/]] and Maven Central. +  * 添加以下的 Maven 仓库：Fabric [[https://maven.fabricmc.net/]]、Mojang [[https://libraries.minecraft.net/]] 和 Maven Central。 
-  * Configures the ''idea'' extension to exclude directories ''.gradle'', ''build'', ''.idea'' and ''out'', to download javadocs sources and to inherit output directories. +  * 配置 ''idea'' 扩展以排除目录 ''.gradle''、''build''、''.idea'' 和 ''out''，以下载 javadocs 源，并继承输出目录。 
-  * Configures the ''idea'' task to be finalized by the ''genIdeaWorkspace'' task. +  * 配置 ''idea'' 任务，并由 ''genIdeaWorkspace'' 任务确定。 
-  * Configures the ''eclipse'' task to be finalized by the ''genEclipseRuns'' task. +  * 配置 ''eclipse'' 任务，并由 ''genEclipseRuns'' 任务确定。 
-  * If an ''.idea'' folder exists in the root project, downloads assets (if not up-to-date) and installs run configurations in ''.idea/runConfigurations''. +  * 如果根项目存在 ''.idea'' 文件夹，下载资源（如果没有及时更新）并在 ''.idea/runConfigurations'' 安装 run 配置。 
-  * Adds ''net.fabricmc:fabric-mixin-compile-extensions'' and its dependencies with the ''annotationProcessor'' dependency configuration. +  * 添加 ''net.fabricmc:fabric-mixin-compile-extensions'' 以及其依赖，使用 ''annotationProcessor'' 依赖配置。 
-  * Configures all non-test JavaCompile tasks with configurations for the Mixin annotation processor. +  * 配置所有的非 test JavaCompile 任务，使用 Mixin 注解处理器的配置。 
-  * Configures the ''remapJar'' task to output a JAR with the same name as the ''jar'' task output, then adds a "dev" classifier to the ''jar'' task. +  * 配置 ''remapJar'' 任务，输出名称与 ''jar'' 任务输出的相同的 JAR，然后给 ''jar'' 任务添加一个“dev”分类器。 
-  * Configures the ''remapSourcesJar'' task to process the ''sourcesJar'' task output if the task exists. +  * 配置 ''remapSourcesJar'' 任务，以处理 ''sourcesJar'' 任务输出，如果该任务存在。 
-  * Adds the ''remapJar'' task and the ''remapSourcesJar'' task as dependencies of the ''build'' task. +  * 将 ''remapJar'' 任务和 ''remapSourcesJar'' 任务添加为 ''build'' 任务的依赖。 
-  * Configures the ''remapJar'' task and the ''remapSourcesJar'' task to add their outputs as ''archives'' artifacts when executed. +  * 配置 ''remapJar'' 任务和 ''remapSourcesJar'' 任务以在执行时将其输出添加为 ''archives'' 成品。 
-  * For each MavenPublication (from the ''maven-publish'' plugin): +  * 为每个 MavenPublication （从 ''maven-publish'' 插件）： 
-    * Manually appends dependencies to the POM for mod-augmented dependency configurations, provided the dependency configuration has a Maven scope.+    * 手动将依赖附加到 POM 之后，以进行模组增强的依赖配置，前提是依赖配置具有 Maven 范围。
  
-All run configurations have the run directory ''${projectDir}/run'' and the VM argument ''-Dfabric.development=true''. The main classes for run configurations is usually defined by a ''fabric-installer.json'' file in the root of Fabric Loader's JAR file when it is included as a mod dependency, but the file can be defined by any mod dependency. If no such file is found, the main classes defaults to ''net.fabricmc.loader.launch.knot.KnotClient'' and ''net.fabricmc.loader.launch.knot.KnotServer''.+所有的运行配置都有运行目录 ''${projectDir}/run'' 和 VM 参数 ''-Dfabric.development=true''。运行配置的主类通常是由 Fabric 加载器 JAR 文件的根部的 ''fabric-installer.json'' 文件定义的（如果该文件包含在模组依赖中的话），但是文件可以由模组依赖定义。如果没有找到这样的文件，则主类默认为 ''net.fabricmc.loader.launch.knot.KnotClient'' 和 ''net.fabricmc.loader.launch.knot.KnotServer''。
  
-The client run configuration is configured with ''--assetsIndex'' and ''--assetsDir'' program arguments pointing to the loom cache directory containing assets and the index file for the configured version of Minecraft. When running on OSX, the "-XstartOnFirstThread" VM argument is added.+客户端运行配置是使用 ''--assetsIndex'' 和 ''--assetsDir'' 程序参数配置的，指向包含资源文件和配置的 Minecraft 版本的索引文件的 loom 缓存目录。在 OSX 上运行时，添加了 ''-XstartOnFirstThread'' VM 参数。
  
zh_cn/documentation/fabric_loom.1647699848.txt.gz · Last modified: 2022/03/19 14:24 by solidblock