User Tools

Site Tools



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

Link to this comparison view

Next revision
Previous revision
zh_cn:tutorial:mappings [2019/12/18 11:23]
lightcolour created
zh_cn:tutorial:mappings [2020/11/17 03:48] (current)
solidblock [使用映射]
Line 1: Line 1:
-====== ​Mappings ​======+====== ​映射 ​======
-==== Introduction ​====+==== 定义 ​====
-Mappings define the names of classes, fields and methods. In an ordinary ​loom environment, ​[[https://​​FabricMC/​yarn|Yarn]] ​mappings are used, which provide meaningful names for the Minecraft ​codebase as decided by the community. ​[[https://​​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://​​FabricMC/​yarn|Yarn]]映射,这是社区决定的,它为Minecraft的代码库提供了有意义的名称。[[https://​​FabricMC/​intermediary|Intermediary]]也是Fabric使用的一个必要的映射类型。对映射的需要来自Minecraft发布的混淆(obfuscation),这代表了多个挑战。重映射(remapping)是对编译的类或者源代码文件应用映射的过程。 
 +==== 使用映射 ==== 
-==== Using mappings ==== +YarnLoom使用的默认映射。随着对贡献的接受,Yarn逐渐改进并接受新的发布。Loom中的映射是使用buildcraft中的''​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. +
- +
-Yarn is the default mapping used by LoomYarn 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>​ <​code>​
Line 18: Line 16:
 </​code>​ </​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 transparently可以为您处理这个转换,但是使用反射(reflection)时要谨慎。 
 +=== Mojang的映射 === 
 +对于Loom 0.5,你也可以使用Mojang的官方映射而不是Yarn,像这样: 
 +dependencies { 
 +    [...] 
 +    mappings minecraft.officialMojangMappings() 
-=== Custom mappings ​===+=== 自定义映射 ​===
-You can use custom tiny mappings for Fabric Loom for your Gradle project setup.+您也可以在您的Gradle项目设置为Fabric Loom使用自定义的微型(tiny)映射。
-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>​
Line 38: Line 48:
 </​code>​ </​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代码都可以重新映射。 它涉及根据映射更改引用的名称,以及仔细重命名方法以保留替代。 尽管它将影响反射中使用的名称,但它不会更改代码的功能。
-[[https://​​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://​​FabricMC/​tiny-remapper|微小的重新映射]] 是可以重新映射已编译Java代码的工具。 它具有命令行界面和可编程界面。 ​Loom使用Tiny Remapper完成许多任务,Fabric Loader使用Tiny RemapperMinecraft代码重新映射到中介。 ​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代码并为其创建mod。 映射可以提供类,字段,方法,参数和局部变量的名称。 显然,这些映射并不完美。 绘制《我的世界》的整个地图需要来自多个贡献者的大量猜测。 映射可能不完整,有时会随着找到更准确的名称而更改。
-==== 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作为mods的库时,由于缺乏二进制兼容性,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内部定义稳定名称。中介名称的目的是始终引用相同的类,字段或方法。与纱线名称不同,中间名称没有意义,而是遵循数字模式,例如''​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所应用的中间名称编译的Mod与此环境自然兼容。
zh_cn/tutorial/mappings.1576668184.txt.gz · Last modified: 2019/12/18 11:23 by lightcolour