Differences

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

--- zh_cn:tutorial:mappings [2019/12/18 11:23] – created lightcolour
+++ zh_cn:tutorial:mappings [2024/04/15 00:57] (current) – solidblock
@@ Line 1: / Line 1: @@
-====== Mappings ======
+====== 映射 ======
-==== Introduction ====
+==== 定义 ====
-Mappings define the names of classes, fields and methods. In an ordinary loom environment, [[https://github.com/FabricMC/yarn|Yarn]] mappings are used, which provide meaningful names for the Minecraft codebase as decided by the community. [[https://github.com/FabricMC/intermediary|Intermediary]] is also an essential type of mapping used by Fabric. The need for mappings comes from the obfuscation of Minecraft releases, which presents multiple challenges. Remapping is the process of applying mappings to compiled classes or source files.
+映射（mapping）定义了类、字段和方法的名称。在常规的 loom 环境中，使用的是 [[https://github.com/FabricMC/yarn|Yarn]] 映射，这是社区决定的，它为 Minecraft 的代码库提供了有意义的名称。[[https://github.com/FabricMC/intermediary|Intermediary]] 也是 Fabric 使用的一个必要的映射类型。需要映射是因为 Minecraft 发布的混淆（obfuscation），这代表了多个挑战。重映射（remapping）是对编译的类或者源代码文件应用映射的过程。
+==== 使用映射 ====
+在 Loom 中，映射定义了你在开发环境中使用的 Minecraft 类、字段和方法的名称。这些名称可能因开发环境而异，取决于你安装的映射。
-==== Using mappings ====
+Yarn 是 Loom 使用的默认映射。随着对贡献的接受，Yarn 逐渐改进并接受新的发布。Loom 中的映射是使 buildscript 中的 ''mappings'' 依赖配置指定的，可以通过更新依赖来更新。Minecraft 以及包含在模组增强依赖配置中的依赖项（如''modCompile''）都是通过映射来重映射的。不在 Yarn 中映射的类、字段和方法，会以中间名显示，如''class_1234''、''method_1234''、''field_1234''。
-In Loom, the mappings define the names for Minecraft classes, fields and methods used in your development environment. These names may vary from one development environment to another depending on the installed mappings.
+<code groovy>
-Yarn is the default mapping used by Loom. Yarn gradually improves and receives new releases as contributions are accepted. Mappings in Loom are specified using the ''mappings'' dependency configuration in the buildscript and can be updated by updating the dependency. Minecraft as well as dependencies included with mod-augmented dependency configurations like ''modCompile'' are remapped with the mapping. Classes, fields and methods that are not mapped in Yarn are given Intermediary names like ''class_1234'', ''method_1234'' and ''field_1234''.
-<code>
 dependencies {
     [...]
@@ Line 18: / Line 16: @@
 </code>
-By changing the mappings in your development environment, you can expect that names of classes, methods and fields in Minecraft and any included mods have changed, and that your code might have to be updated to reference the changed names. [[tutorial:migratemappings|This process can be partially automated]]. You will also have to run ''genSources'' to access Minecraft sources with the updated mappings.
+右改变您的开发环境中的映射，Minecraft 以及包括的模组中的类、方法和字段的名称都可能会改变，您的代码可能需要更新才能引用更改的名称。[[tutorial:migratemappings|这一过程可以部分自动化]]。你可能也需要运行 ''genSources'' 来运行带有更新的映射的 Minecraft 源代码。
-Loom's ''remapJar'' task will produce the primary mod artifact, which is a built jar using intermediary names. Additionally, if a ''sourcesJar'' task is present, ''remapSourcesJar'' will produce a sources jar using intermediary names. These jars can be installed as mods or included in a development environment with the ''modCompile'' dependency configuration.
+Loom 的 ''remapJar'' 任务会提供原始的模组成品，这个成品是使用中间名的 jar 文件。此外，如果有 ''sourcesJar'' 任务，''remapSourcesJar'' 会产生使用中间名的源代码jar。这些 jar 文件都可以作为模组安装，或者连同 ''modCompile'' 依赖配置一起被包括在开发环境中。
-  * **The '-dev' jar (the ''jar'' task output) does not use intermediary names, and is therefore not useful.** It cannot be installed as a mod outside a development environment and will only work in a development environment with matching mappings. The regular jar (the ''remapJar'' task output) should be used instead and installed in development environments using mod-augmented dependency configurations like ''modCompile''.
+  * **'-dev' jar（''jar'' 任务的输出）不使用中间名，因此无用。**不可以被安装为开发环境之外的模组，且只能在带有相符的映射的开发环境中起作用。常规的jar文件（''remapJar'' 任务输出）才应被使用，并使用像 ''modCompile'' 这样的模组增强依赖项安装在开发环境中。
-  * **Yarn names are only applied in a development environment**. Outside a development environment, only intermediary names exist, meaning the code will not match exactly what you see and wrote. Loom transparently handles this transition for you, but be cautious when using reflection.
+  * **Yarn 名称仅应用于开发环境**。在开发环境之外，只存在中间名，也就是说代码不会准确地匹配你看见和写的东西。Loom 可以透明地为您处理这个转换，但是使用反射（[[reflection]]）时要谨慎。
+=== Mojang 的映射 ===
+自 Loom 0.5，你也可以使用 Mojang 的官方映射而不是 Yarn，像这样：
+<code groovy>
+dependencies {
+    [...]
+    mappings minecraft.officialMojangMappings()
+}
+</code>
+Mojang 的映射带有可用的但比 Yarn 更严格的许可证。您需要自行承担使用的风险。
-=== Custom mappings ===
+=== 自定义映射 ===
-You can use custom tiny mappings for Fabric Loom for your Gradle project setup.
+您也可以在您的 Gradle 项目设置为 Fabric Loom 使用自定义的微型映射。
-For example, if you have a custom branch of yarn which you want to use for mappings, you can build yarn with "./gradlew build" command, take out the jar file in "build/libs" directory, and move it to a folder "mapping" in your Gradle project. Then, change your mappings dependency entry to:
+比如，如果您有需要用于映射的自定义 Yarn 分支，你可以使用“./gradlew build”命令建立 yarn，拿出“build/libs”目录中的 jar 文件，然后移动到您的 Gradle 项目中的“mapping”文件夹下。然后，将您的映射依赖项更改为：
-<code>
+<code yarn>
 dependencies {
     mappings fileTree(dir: "mapping", include: "**.jar")
@@ Line 38: / Line 48: @@
 </code>
-You can change the directory where you put mapping to have any custom name; just change the name in "dir" argument above. Note that Gradle build will fail if you have any other file than the mapping jar in the mapping directory!
+您可以更改放置映射的目录，使其具有任何自定义名称，只需更改上面的“dir”参数中的名称。注意，如果在映射目录中有映射 jar 文件以外的任何其他文件，Gradle构建将失败！
-==== Remapping ====
+==== 重映射 ====
-Remapping is the process of applying mappings to code, transforming from one set of names to another. Both Java source code and compiled Java code can be remapped. It involves changing the names of references according to the mappings, as well as carefully renaming methods to preserve overrides. It does not change what the code does, although it will affect names used in reflection.
+重映射是将映射应用于代码，从一组名称转换为另一组名称的过程。Java 源代码和已编译的 Java 代码都可以重新映射，涉及根据映射更改引用的名称，以及仔细重命名方法以保留替代。这不会更改代码的功能，但可能会影响[[reflection|反射]]中使用的名称。
-[[https://github.com/FabricMC/tiny-remapper|Tiny Remapper]] is a tool that can remap compiled Java code. It has a command line interface as well as a programmable interface. Loom uses Tiny Remapper for a number of tasks, and Fabric Loader uses Tiny Remapper to remap the Minecraft code to intermediary. Loom is also capable of remapping Java source code.
+[[https://github.com/FabricMC/tiny-remapper|Tiny Remapper]] 是可以重映射已编译的 Java 代码的工具，具有命令行界面和可编程界面。Loom 使用 iny Remapper 完成许多任务，Fabric Loader 使用 Tiny Remapper 将 Minecraft 代码重新映射到中介。Loom 还能够重新映射 Java源代码。
-==== Obfuscation and deobfuscation ====
+==== 混淆和反混淆 ====
-Releases of Minecraft Java Edition are obfuscated jar files, which means they are compiled binaries stripped of any meaningful naming information, leaving only the bare logic behind. The motivation behind obfuscation is to prevent reverse engineering and to reduce file sizes. Java programs like Minecraft are rather simple to decompile, but the obfuscation is stripping away a lot of information that would be useful for modding purposes. One might wonder how it is possible to develop for Minecraft in the first place.
+Minecraft Java Edition 的发行版是混淆的 jar 文件，这意味着是已编译的二进制文件，其中剥离了任何有意义的命名信息，仅保留了裸露的逻辑。混淆的目的是防止反向工程并减小文件大小。像 Minecraft 这样的 Java 程序很容易反编译，但是混淆处理剥夺了很多对修改目的有用的信息。也许有人会怀疑一开始如何为 Minecraft 进行开发。
-Mappings like Yarn provide meaningful names for development. Using mappings it is possible to make sense of the Minecraft code and create mods for it. Mapping can provide names for classes, fields, methods, parameters, and local variables. It should be obvious these mappings are not perfect. Mapping the entirety of Minecraft involves a lot guesswork from multiple contributors. Mappings may be incomplete and sometimes change as more accurate names are found.
+像 Yarn 这样的映射为开发提供了有意义的名称。使用映射可以理解 Minecraft 代码并为其创建模组。映射可以提供类、字段、方法、参数和局部变量的名称。显然，这些映射并不完美。完成 Minecraft 的整个映射表需要来自多个贡献者的大量猜测。映射可能不完整，有时会随着找到更准确的名称而更改。
-==== Intermediary ====
+==== 中间名 ====
-A property of Minecraft's obfuscation is that it is not always consistent between Minecraft versions. A class may be called ''abc'' in one version of Minecraft, and ''abd'' in another. The same inconsistency applies to fields and methods. The inconsistency creates binary incompatibility between Minecraft versions.
+Minecraft 的混淆有个特点，在 Minecraft 版本之间并不总是一致。在 Minecraft 的一个版本中，一个类可能被称为 ''abc''，而在另一个版本中则被称为 ''abd''。同样的不一致也适用于字段和方法。不一致会导致 Minecraft 版本之间的二进制不兼容。
-Java code may be compiled for one version of a library and still work with another, making the two versions of the library binary compatible. Put simply, binary compatibility is achieved if the library exposes at least the same classes with the same methods and fields with the same names. The inconsistency in Minecraft's obfuscation presents a challenge when using Minecraft as a library for mods because of the lack of binary compatibility.
+Java 代码可以针对一个库版本进行编译，但仍可与另一个版本一起使用，从而使库的两个版本可以二进制兼容。简而言之，如果库公开了至少相同的类，相同的方法和具有相同名称的字段，则将实现二进制兼容性。当使用 Minecraft 作为模组的库时，由于缺乏二进制兼容性，Minecraft 的混淆问题（为模组在不同游戏版本间的兼容性）带来了挑战。
-Intermediary defines stable names for Minecraft's internals across Minecraft versions. The purpose of an Intermediary name is that it will always refer to the same class, field or method. Unlike Yarn names, Intermediary names are not meaningful and instead follow a numeric pattern like ''class_1234'', ''method_1234'' and ''field_1234''.
+中间名在 Minecraft 版本之间为 Minecraft 内部定义稳定名称。中间名称的目的是始终引用相同的类、字段或方法。与 Yarn 名称不同，中间名称没有意义，而是遵循数字模式，例如 ''class_1234''、''method_1234'' 和 ''field_1234''。
-Being a stable mapping, Intermediary can make Minecraft binary compatible across multiple versions (such as snapshot versions)! Compatibility is guaranteed only for the parts of the game that are unchanged between versions. When installed outside a development environment, Fabric Loader provides an environment with intermediary names by remapping Minecraft (and the Realms client) before the game is started. This can be observed by looking at a crash report from a production environment with Fabric Loader installed, which will contain intermediary names. Mods, compiled with intermediary names as applied by Loom, are naturally compatible with this environment.
+作为稳定的映射，中间名可以使 Minecraft 二进制兼容多个版本（例如快照版本）！但需要注意的是，它仅对于版本之间未更改的游戏部分才保证兼容性。当安装在开发环境之外时，Fabric Loader 通过在游戏开始之前重映射 Minecraft（和 Realms 客户端）来为环境提供中间名称。通过查看安装了 Fabric Loader 的生产环境中的崩溃报告可以观察到此情况，该报告将包含中间名称。用 Loom 所应用的中间名称编译的模组与此环境自然兼容。