User Tools

Site Tools



















This is an old revision of the document!



映射定义类,字段和方法的名称。 在普通的织机环境中,使用Yarn映射,该映射为社区确定的Minecraft代码库提供了有意义的名称。 Intermediary也是Fabric使用的基本映射类型。 对映射的需求来自对Minecraft版本的混淆,这带来了许多挑战。 重新映射是将映射应用于已编译的类或源文件的过程。


在Loom中,映射定义了开发环境中使用的Minecraft类,字段和方法的名称。 根据安装的映射,这些名称可能因开发环境而异。

毛线是Loom使用的默认映射。 随着贡献的增加,纱线会逐渐改进并获得新的版本。 使用构建脚本中的“映射”依赖项配置来指定Loom中的映射,并且可以通过更新依赖项来进行更新。 Minecraft以及mod增强的依赖项配置(例如 modCompile )中包含的依赖项均通过映射进行映射。 未在Yarn中映射的类,字段和方法的中间名称为class_1234method_1234field_1234

dependencies {
    mappings "net.fabricmc:yarn:${project.yarn_mappings}"

通过更改开发环境中的映射,可以预期Minecraft中的类,方法和字段的名称以及所有包含的mod均已更改,并且可能必须更新代码以引用更改后的名称。 此过程可以部分自动化。 您还必须运行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.

  • 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.
  • 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.

Custom mappings

You can use custom tiny mappings for Fabric Loom for your Gradle project setup.

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:

dependencies {
    mappings fileTree(dir: "mapping", include: "**.jar")

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!


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.

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.

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.

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.


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.

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.

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.

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.

zh_cn/tutorial/mappings.1576668321.txt.gz · Last modified: 2019/12/18 11:25 by lightcolour