Differences

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

--- zh_cn:documentation:fabric_loom [2022/03/20 13:11] – solidblock
+++ zh_cn:documentation:fabric_loom [2024/08/17 11:07] (current) – Sync jeffreyg1228
@@ Line 1: / Line 1: @@
 ====== 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]]。
-  * ''remapJar''：产生包含 ''jar'' 任务的重映射的输出的 jar。同时也会将 jar 中 jar 包含在模组中。运行 ''build'' 时会调用。
+  * ''remapJar''：产生包含 ''jar'' 任务的重映射的输出的 jar。同时也会将 jar-in-jar 包含在模组中。运行 ''build'' 时会调用。
   * ''genSources''：使用默认的反编译器（CFR）反编译 Minecraft jar。
   * ''downloadAssets''：下载配置的 Minecraft 版本的资源索引和对象，下载到用户缓存中。
   * ''genEclipseRuns''：安装 Eclipse 运行配置并创建运行目录（如果还不存在）。
   * ''vscode''：生成或覆盖 Visual Studio Code 的 ''launch.json'' 文件，启动配置在 ''.vscode'' 文件夹中，并创建运行目录，如果还不存在。
+  * ''ideaSyncTask''：生成（但是不会覆盖）Intellij IDEA 的启动配置，包括客户端和服务器。
   * ''remapSourcesJar''：只有在 AbstractArchiveTask ''sourcesJar'' 存在时存在。将 ''sourcesJar'' 任务的输出重映射。
   * ''runClient''：将 Fabric Loader 作为 Minecraft 客户端运行的 JavaExec 任务。
@@ Line 21: / Line 22: @@
 <code>
 dependencies {
-	implementation project(path: ":name", configuration: "namedElements")
+    implementation project(path: ":name", configuration: "namedElements")
 }
 </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 86: / Line 119: @@
 			source = sourceSets.test
 		}
+		// 删除内置服务器配置的示例
+                remove server
 	}
@@ Line 95: / Line 131: @@
 	// 用于配置 mixin 选项，或应用到额外的源集。
 	mixin {
-		// 若禁用，会使用微小重映射器来重映射 Mixin 而非 AP。实验性。
+		// 若禁用，会使用 tiny remapper 来重映射 Mixin 而非 AP。实验性。
 		useLegacyMixinAp = true
 		// 设置默认的 refmap 名称
@@ Line 122: / Line 158: @@
 		enableDependencyInterfaceInjection = true
 	}
+	// 将 Minecraft jar 和传入的依赖项拆分到 main（common）和仅限客户端的源集。
+	// 这可以在编译期间就确保访问仅限客户端的代码时的安全。
+	splitEnvironmentSourceSets()
+	// 这个 mods 语句块用于将由多个类路径的项组合在一起。
+	mods {
+		modid {
+			// 使用分离的资源时，你应该添加 main 和 common 源集
+			sourceSet sourceSets.main
+			sourceSet sourceSets.client
+		}
+	}
+	// 创建 modExampleImplementation 和重映射 mods 的相关配置。
+	createRemapConfigurations(sourceSets.example)
 }
@@ Line 199: / Line 251: @@
 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).
+  - 处理并包含模组增强的依赖。
 ==== 缓存 ====
-  * ''${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''：定义用于开发环境的 Minecraft 版本。
   * ''mappings''：定义用于开发环境的映射。
-  * ''modCompile''、''modImplementation''、''modApi'' 和''modRuntime''：相当于''compile''、''implementation''、''api''和''runtime''的增强型变种，用于模组依赖。会被重映射以对应开发环境，并且会移除嵌套的 JAR。可以选择导出并重映射嵌套的 JAR。
+  * ''modCompile''、''modImplementation''、''modApi'' 和''modRuntime''：相当于''compile''、''implementation''、''api''和''runtime''的增强型变种，用于模组依赖。会被重映射以对应开发环境，并且会移除嵌套的 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 参数。