Fabric Loom，或者简称为 Loom，是个 Gradle 插件，用于 Fabric 生态系统的模组开发中。Loom 提供了在开发环境中安装 Minecraft 和模组的一系列工具，所以你可以针对 Minecraft 混淆及其发行版和版本之间的差异来将 Loom 与 Minecraft 链接起来。Loom 还提供了用于 Fabric 加载器的运行配置、mixin 编译处理，以及用于 Fabric Loader 的 jar 中 jar 系统的工具。

• migrateMappings：将当前源代码合并到指定的映射中。见 migratemappings。
• remapJar：产生包含 jar 任务的重映射的输出的 jar。同时也会将 jar 中 jar 包含在模组中。运行 build 时会调用。
• genSources：使用默认的反编译器（CFR）反编译 Minecraft jar。
• downloadAssets：下载配置的 Minecraft 版本的资源索引和对象，下载到用户缓存中。
• genEclipseRuns：安装 Eclipse 运行配置并创建运行目录（如果还不存在）。
• vscode：生成或覆盖 Visual Studio Code 的 launch.json 文件，启动配置在 .vscode 文件夹中，并创建运行目录，如果还不存在。
• remapSourcesJar：只有在 AbstractArchiveTask sourcesJar 存在时存在。将 sourcesJar 任务的输出重映射。
• runClient：将 Fabric Loader 作为 Minecraft 客户端运行的 JavaExec 任务。
• runServer：将 Fabric Loader 作为 Minecraft 专用服务器运行的 JavaExec 任务。

设立依赖其他 loom 项目的多项目构建时，你应该在依赖其他项目时使用 namedElements 配置。默认情况下，项目的“输出”会映射到中间名。namedElements 配置包含还未重映射的项目输出。

dependencies {
	implementation project(path: ":name", configuration: "namedElements")
}

loom {
	// 设置访问加宽的路径，参见 https://fabricmc.net/wiki/zh_cn:tutorial:accesswideners
	accessWidenerPath = file("src/main/resources/modid.accesswidener")

	// 添加额外的 log4j 配置文件。
	log4jConfigs.from(file("log4j.xml"))

	// 若启用，输出的存档会自动重映射。
	remapArchives = true
	// 若启用，*Elements 配置中的 -dev jars 会被替换为重映射的 jar。
	setupRemappedVariants = true
	// 若启用，传递性的访问加宽会从依赖中应用。
	enableTransitiveAccessWideners = true
	// 若启用，log4j 只会在运行时类路径中，强制使用 SLF4j。
	runtimeOnlyLog4j = false

	// 若启用，只有与服务器有关的特性和 jars 会被设置。
	serverOnlyMinecraftJar()
	// 若设置，minecraft jar 会分为常规和仅客户端。这只是实验性的。Fabric 加载器暂时还不支持这个功能。
	splitMinecraftJar()

	// 用于配置存在的或者新的运行配置
	runs {
		client {
			// 添加 VM 变量
			vmArgs "-Dexample=true"
			// 添加 JVM 属性
			property("example", "true")
			// 添加 program 变量
			programArg "--example"
			// 需要运行的环境（或端），通常是 client 或 server。
			environment = "client"
			// 运行配置的完整名称，例如“Minecraft 客户端”。默认由基础名称决定。
			configName = "Minecraft 客户端"
			// 运行配置的默认主类。使用带有 fabric_installer.json 文件的模组加载器时，就会覆盖这个。
			defaultMainClass = ""
			// 此配置的运行目录，与根项目目录有关。
			runDir = "run"
			// 运行的源集，通常设为 sourceSets.test
			source = sourceSets.main
			// 若为 true，运行配置会为 IDE 生成。默认仅对根项目为 true。
			ideConfigGenerated = true

			// 配置以默认的客户端选项运行配置。
			client()

			// 配置以默认的服务器选项运行配置。
			server()
		}

		// 为测试创建基本运行配置的示例
		testClient {
			// 从另一个运行配置复制设置。
			inherit client

			configName = "测试 Minecraft 客户端"
			source = sourceSets.test
		}
	}

	// 配置所有运行配置以生成 ide 运行配置。对子项目很有用。
	runConfigs.configureEach {
		ideConfigGenerated = true
	}

	// 用于配置 mixin 选项，或应用到额外的源集。
	mixin {
		// 若禁用，会使用微小重映射器来重映射 Mixin 而非 AP。实验性。
		useLegacyMixinAp = true
		// 设置默认的 refmap 名称
		defaultRefmapName = "example.refmap.json"

		// 关于添加额外资源集的选项，参见 https://github.com/FabricMC/fabric-loom/blob/dev/0.11/src/main/java/net/fabricmc/loom/api/MixinExtensionAPI.java
	}

	// 配置或添加新的反编译器
	decompilers {
		// 配置默认的反编译器，cfr 或 fernflower
		cfr {
			// 将额外选项传递到编译器
			options += [
				key: "value"
			]
			// 设置分叉 JVM 时使用的内存量（以兆字节为单位）
			memory = 4096
			// 设置反编译器可以使用的最大线程数。
			maxThreads = 8
		}
	}

	interfaceInjection {
		// 若启用，将会应用配置的注入的接口。
		enableDependencyInterfaceInjection = true
	}
}

remapJar {
	// 设置任务的输出 jar，同样对 remapSourcesJar 有效
	inputFile = file("example.jar")
	// 设置资源命名空间，同样对 remapSourcesJar 有效
	sourceNamespace = "named"
	// 设置目标命名空间，同样对 remapSourcesJar 有效
	targetNamespace = "intermediary"
	// 给重映射类路径添加额外的 jar，同样对 remapSourcesJar 有效
	classpath.from file("classpath.jar")

	// 将嵌套的模组 jar 添加到该任务，include 配置应该用于 maven 库和模组。
	nestedJars.from file("nested.jar")
	// 若启用，输出的 jar 中会包含嵌套的 jar。
	addNestedDependencies = true
}

dependencies {
	// 设置 Minecraft 版本。
	minecraft "com.mojang:minecraft:1.18.1"

	// 使用 maven 中的映射。
	mappings "net.fabricmc:yarn:1.18.1+build.22:v2"

	// 使用官方 mojang 映射
	mappings loom.officialMojangMappings()

	// 使用官方 mojang 映射和 parchment 的分层映射。
	mappings loom.layered() {
		officialMojangMappings()
		// 使用 parchment 映射。注意：必须手动添加 Parchment maven（https://maven.parchmentmc.org）
		parchment("org.parchmentmc.data:parchment-1.17.1:2021.09.05@zip")
	}

	// 从 maven 中重映射一个模组，并应用到 gradle 的 implementation 配置
	// （小的细节：不会准确地应用*到*配置，但是会克隆一份以用于模组依赖）
	modImplementation "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"

	// 从 maven 中重映射一个模组，并应用到 gradle 的 api 配置
	modApi "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"

	// 从 maven 中重映射一个模组，并应用到 gradle 的 compileOnly 配置
	modCompileOnly "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"

	// 从 maven 中重映射一个模组，并应用到 gradle 的 compileOnlyApi 配置
	modCompileOnlyApi "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"

	// 从 maven 中重映射一个模组，并应用到 gradle 的 runtimeOnly配置
	modRuntimeOnly "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"

	// 从 maven 中重映射一个模组，并应用到 loom 的 localRuntime 配置。
	// 和 runtimeOnly 的做法类似，但是不会暴露到依赖项中。有点像 testRuntimeOnly，不过是对于模组的。
	modLocalRuntime "net.fabricmc.fabric-api:fabric-api:0.46.2+1.18"

	// 在重映射的 jar 中包含一个模组 jar。不可传递。
	include "example:example-mod:1.1.1"

	// 在重映射的 jar 中包含一个空模组库。会生成空模组。不可传递。
	include "example:example-lib:1.1.1"

	// 根据特定的结构 api 版本提供帮助的助手。
	modImplementation fabricApi.module("fabric-api-base", "0.46.2+1.18")

	// 使用 namedElements 配置，依赖一个 loom 子项目。
	implementation project(path: ":name", configuration: "namedElements")
}

Loom 或者 gradle 可能会由于缓存文件有问题而失败。运行 ./gradlew build –refresh-dependencies 将强制 gradle 和 loom 重新下载并重新创建所有文件。这可能需要几分钟，但是处理与缓存有关的问题时非常有用。

Loom 旨在通过简单地在用户选择的 IDE 中设置工作区来开箱即用，因此背后做了很多事以创建带有 Minecraft 的开发环境：

1. 从官方渠道下载指定版本 Minecraft 的客户端和服务器 jar。
2. 将客户端和服务器 jar 合并到一起以生成一个合并的 jar，并加上 @Environment 和 @EnvironmentInterface 注解。
3. 下载配置的映射。
4. 使用中间映射重映射合并的 jar 产生一个中间 jar。
5. 使用 yarn 映射重映射合并的 jar 产生一个映射的 jar。
6. 可选的：Optional: 反编译映射了的 jar 产生一个映射的源 jar 和行映射，并将行映射应用到合并的 jar。
7. 添加 Minecraft 的依赖。
8. 下载 Minecraft 资源文件（assets）。
9. 处理并包含模组增强的依赖（还可以导出并重映射嵌套的 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/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.
• build/loom-cache: The root project build cache.
• **/build/loom-cache: The (sub)project build cache.

• minecraft：定义用于开发环境的 Minecraft 版本。
• mappings：定义用于开发环境的映射。
• modCompile、modImplementation、modApi 和modRuntime：相当于compile、implementation、api和runtime的增强型变种，用于模组依赖。会被重映射以对应开发环境，并且会移除嵌套的 JAR。可以选择导出并重映射嵌套的 JAR。
• include：生命一个应在 remapJar 输出中包含的 jar 中 jar 依赖。该依赖配置是不可传递的。对于非模组依赖，Loom 会生成一个模组 JAR，其中 fabric.mod.json 使用模组 ID 的名称和相同版本。

• Applies the following plugins: java, eclipse and idea.
• Adds the following Maven repositories: Fabric https://maven.fabricmc.net/, Mojang https://libraries.minecraft.net/ and Maven Central.
• Configures the idea extension to exclude directories .gradle, build, .idea and out, to download javadocs sources and to inherit output directories.
• Configures the idea task to be finalized by the genIdeaWorkspace task.
• Configures the eclipse task to be finalized by the genEclipseRuns task.
• If an .idea folder exists in the root project, downloads assets (if not up-to-date) and installs run configurations in .idea/runConfigurations.
• Adds net.fabricmc:fabric-mixin-compile-extensions and its dependencies with the annotationProcessor dependency configuration.
• Configures all non-test JavaCompile tasks with configurations for the Mixin annotation processor.
• 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.
• Configures the remapSourcesJar task to process the sourcesJar task output if the task exists.
• Adds the remapJar task and the remapSourcesJar task as dependencies of the build task.
• Configures the remapJar task and the remapSourcesJar task to add their outputs as archives artifacts when executed.
• For each MavenPublication (from the maven-publish plugin):
  • Manually appends dependencies to the POM for mod-augmented dependency configurations, provided the dependency configuration has a Maven scope.

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.

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.