Fabric Wiki

User Tools

Site Tools

Trace: • 添加方块实体
zh_cn:documentation:fabric_loom

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
zh_cn:documentation:fabric_loom [2022/03/19 14:27] – [依赖配置] 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''：项目和子项目的构建缓存。
 ==== 依赖配置 ==== ==== 依赖配置 ====
  
Line 221: Line 266:
   * ''mappings''：定义用于开发环境的映射。   * ''mappings''：定义用于开发环境的映射。
   * ''modCompile''、''modImplementation''、''modApi'' 和''modRuntime''：相当于''compile''、''implementation''、''api''和''runtime''的增强型变种，用于模组依赖。会被重映射以对应开发环境，并且会移除嵌套的 JAR。可以选择导出并重映射嵌套的 JAR。   * ''modCompile''、''modImplementation''、''modApi'' 和''modRuntime''：相当于''compile''、''implementation''、''api''和''runtime''的增强型变种，用于模组依赖。会被重映射以对应开发环境，并且会移除嵌套的 JAR。可以选择导出并重映射嵌套的 JAR。
-  * ''include''：生命一个应在 ''remapJar'' 输出中包含的 jar 中 jar 依赖。该依赖配置是不可传递的。对于非模组依赖，Loom 会生成一个模组 JAR，其中 fabric.mod.json 使用模组 ID 的名称和相同版本。+  * ''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.1647700058.txt.gz · Last modified: 2022/03/19 14:27 by solidblock