Differences

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

--- tutorial:mappings [2025/11/04 10:14] – Replace link to tutorial:migratemappings with Docs link to develop/migrating-mappings gauntrecluse
+++ tutorial:mappings [2026/03/01 23:56] (current) – Status updating on mappings cassiancc
@@ Line 3: / Line 3: @@
 ==== 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.
+Mappings defined the names of classes, fields and methods on obfuscated Minecraft versions including 1.21.11 and below. Developers using Fabric for these versions primarily use either Fabric's [[https://github.com/FabricMC/yarn|Yarn]] mappings, which provide meaningful names for the Minecraft codebase as decided by the community, or the official Mojang Mappings, available since 1.14 and providing official names for the entirety of Minecraft. [[https://github.com/FabricMC/intermediary|Intermediary]] mappings were also used by Fabric to provide a stable base for community mappings. The need for mappings came from the fact that Minecraft releases prior to 26.1 were obfuscated, which presents multiple challenges. Remapping is the process of applying mappings to compiled classes or source files.
 ==== Using mappings ====
-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.
+When using a variant of Loom that supports remapping, 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 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''.
+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 ''modCompileOnly'' and ''modImplementation'' are remapped to your chosen mappings. If your mapping layer is incomplete, you may notice classes, fields and methods will use Intermediary names like ''class_1234'', ''method_1234'' and ''field_1234''.
+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. [[https://docs.fabricmc.net/develop/migrating-mappings|This process can be partially automated]]. You will also have to run ''genSources'' to access Minecraft sources with the updated mappings.
+Loom's ''remapJar'' task will produce the primary mod artifact, which is a built jar using intermediary names. However it does not perform testing or validation, ''build'' should always be used to produce JARs for end user use. 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''.
+  * **These 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.
+=== Applying Fabric's Yarn mappings ===
+Yarn was a community developed mapping set that was the default for Fabric users from Fabric's inception until 1.21.10. If you are referencing older tutorials, or prefer the names, you can apply it like this:
 <code>
@@ Line 18: / Line 29: @@
 </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. [[https://docs.fabricmc.net/develop/migrating-mappings|This process can be partially automated]]. You will also have to run ''genSources'' to access Minecraft sources with the updated mappings.
+=== Applying Mojang's mappings ===
-Loom's ''remapJar'' task will produce the primary mod artifact, which is a built jar using intermediary names. However it does not perform testing or validation, ''build'' should always be used to produce JARs for end user use. 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.
+Since 1.14, Mojang has provided its own official mappings rather than Yarn. Note that unlike Yarn, Mojang Mappings do not include paramater names or Javadocs. If you are referencing newer tutorials, prefer the names, or plan to upgrade your mod to 26.1 or above, you can apply it like this:
-  * **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''.
+<code>
-  * **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.
+dependencies {
+    [...]
+    mappings loom.officialMojangMappings()
+}
+</code>
-=== Mojang's mappings ===
+Mojang's mappings come with a usable yet more restrictive license than Yarn. Use them at your own risk.
-As of Loom 0.5, you can also use Mojang's official mappings rather than Yarn, like this:
+=== Applying Parchment's mappings ===
+Users of Mojang Mappings may wish to have paramater names and Javadocs. For that purpose, third party projects like [[https://parchmentmc.org/docs/getting-started|Parchment]] exist. Parchment parameter names and docs are applied via layered mappings on top of Mojang mappings like this:
 <code>
 dependencies {
     [...]
-    mappings loom.officialMojangMappings()
+     mappings loom.layered() {
+         officialMojangMappings()
+         parchment("org.parchmentmc.data:parchment-${project.parchment_mappings}@zip")
+     }
 }
 </code>
@@ Line 39: / Line 59: @@
-=== Custom mappings ===
+=== Applying Custom mappings ===
 You can use custom [[documentation:tiny2|tiny mappings]] for Fabric Loom for your Gradle project setup.
@@ Line 70: / Line 90: @@
 ==== 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.
+Releases of Minecraft Java Edition prior to 26.1 snapshots 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 obfuscation stripped away a lot of information that would be useful for modding purposes. One might wonder how it was possible to develop for these obfuscated versions 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.
+Mappings like Yarn provided 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 involved a lot of guesswork from multiple contributors. Mappings may be incomplete and sometimes change as more accurate names are found.
 ==== Intermediary ====
@@ Line 82: / Line 102: @@
 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.
+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 on an obfuscated version 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.