Differences

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

--- tutorial:migratemappings [2020/01/13 20:38] – rewrite mercury section jamie
+++ tutorial:migratemappings [2025/10/31 21:04] (current) – typo cassiancc
@@ Line 1: / Line 1: @@
-====== Updating Yarn mappings in a Java codebase ======
+:!: //A more thorough documentation of the process of migrating mappings, along with better, specific tooling is currently planned for the near future in order to help the transition into the non-obfuscated MC versions. This page will likely redirect to the proper documentation once it is in a satisfying state.//
-====== Loom 0.2.6 and above ======
-Currently, this process will only affect Java files.
-Say you want to migrate from 1.14.4 to 19w46b.
+====== Migrating to Yarn or Mojang Mappings in a Java codebase ======
-  - Go [[https://modmuss50.me/fabric.html?&version=19w46b|here]], select ''19w46b'', and copy the ''yarn_mappings'' value, for example ''19w46b+build.1''.  DO NOT modify your gradle.properties or build.gradle yet.
+Loom allows semi-automatic updating of the mappings used in a Java codebase. This can be a useful tool for users wishing to keep their codebase up-to-date with the new changes in Yarn, or for users wishing to change to different mappings, including Mojang's own mappings. For more information, check out the dedicated [[tutorial:mappings|Mappings]] page.
-  - In the root of your gradle project, run ''gradlew migrateMappings %%--%%mappings %%"%%19w46b+build.1%%"%%''
-  - Your migrated source will appear in ''remappedSrc''. Verify your code was not nuked and copy it over.
-  - Update your gradle.properties file according to the instructions in [[https://modmuss50.me/fabric.html?&version=19w46b|this]] site.
-  - You're done.
-=== Additional customization ===
+Loom does not support migrating code written in Kotlin. [[https://github.com/Deftu/ReplayMod-Remap|Third party tools]] are available.
-  * Specify from where to take your Java files with ''%%--%%input path/to/source''. Default: ''src/main/java''.
-  * Specify where to output the remapped source with ''%%--%%output path/to/output''. Default: 'remappedSrc'.
-  * Specify a custom place to retrieve the mappings from with ''%%--%%mappings some_group:some_artifact:some_version:some_qualifier''. Default: ''net.fabricmc:yarn:<version-you-inputted>:v2''.
-=== Reporting issues ===
+**Note:** This automated process does not yet handle Mixins or reflection. Updated tooling is currently in the works that will fix these errors. This tooling will be available before the mandatory switch to Mojang names in a future version of Minecraft.
-Loom uses [[https://github.com/CadixDev/Mercury|Mercury]] to remap mods' source code, for problems with remapping please report issues to their [[https://github.com/CadixDev/Mercury/issues|issue tracker]], or discuss it through their communications channel (irc.esper.net #cadix).
-====== Loom 0.2.5 and below ======
-==== Requirements ====
+===== Migrating to Mojang Mappings =====
-  * Fabric-Loom 0.2.2 or above
+These instructions cover migration from Yarn to Mojang Mappings.
-  * A Java codebase - Kotlin and Scala will not, currently, do.
-  * Some assembly required
-==== Instructions ====
+  - You'll need a command to migrate your mappings to Mojang Mappings, for example ''gradlew migrateMappings %%--%%mappings %%"%%net.minecraft:mappings:1.21.10%%"%%''. Replace ''1.21.10'' with the version of Minecraft you are migrating from. This must be the same version of Minecraft you are currently running. DO NOT modify your ''gradle.properties'' or ''build.gradle'' yet.
+  - Run the command in the root of your Gradle project, either through the terminal, or by adding it as a run configuration in IntelliJ Idea.
+  - Your migrated sources will appear in ''remappedSrc''. Verify that the migration produced valid migrated code.
+  - Copy the sources from ''remappedSrc'' to the original folder. Keep the original sources backed up just in case.
+  - If you are coming from Yarn, you can now replace your mappings in your build.gradle with Mojang Mappings (i.e. mappings ''loom.officialMojangMappings()'').
+  - Refresh the Gradle project in your IDE.
+  - Check and update any Mixin targets that may be outdated.
-  - Figure out your target mappings version. For example, "net.fabricmc:yarn:1.14.1 Pre-Release 2+build.2".
+===== Migrating to Yarn =====
-  - Make sure the mappings for this version get created. This is the hacky part, as currently the only way to do it is to edit the "minecraft" and "mappings" fields in a build.gradle to the new version, run any Gradle command ("gradle build" will do, even if it crashes), then **change the fields back**.
-  - Run the following magical wizardry command: ''%%gradle migrateMappings -PtargetMappingsArtifact="net.fabricmc:yarn:1.14.1 Pre-Release 2+build.2" -PinputDir=src/main/java -PoutputDir=remappedSrc%%'', where:
-    * "targetMappingsArtifact" refers to the target mappings version. It is imperative that the build.gradle be set to the current mappings version of the mod when running this command!
-    * "inputDir" is the input directory, containing Java source code,
-    * "outputDir" is the output directory. It will be created if it is missing.
-  - Copy the remapped source code to the input directory, if everything's fine,
-  - Hope for the best.
-//Note: You may need to specify the full paths in quotes, try this if you get file not found issues.//
+These instructions cover migration from Mojang Mappings (or an older version of Yarn) to Yarn.
-This should work across Minecraft versions as well, provided we haven't massively broken Intermediaries or done something equally silly (aka: most of the time).
+  - Go [[https://fabricmc.net/develop|to the Fabric Develop Site]], select the version to migrate to, and copy the Gradle command under "Mappings Migration", for example ''gradlew migrateMappings %%--%%mappings %%"%%1.21.10+build.2%%"%%''.  DO NOT modify your ''gradle.properties'' or ''build.gradle'' yet.
+  - Run the command in the root of your Gradle project, either through the terminal, or by adding it as a run configuration in IntelliJ Idea.
+  - Your migrated sources will appear in ''remappedSrc''. Verify that the migration produced valid migrated code.
+  - Copy the sources from ''remappedSrc'' to the original folder. Keep the original sources backed up just in case.
+  - Update or add to your gradle.properties file with the Yarn version specified on [[https://fabricmc.net/develop|the Develop site]], i.e. ''yarn_mappings=1.21.10+build.2''.
+  - If you are coming from Mojang Mappings, you can now replace your mappings in your build.gradle with Yarn's (i.e. ''mappings "net.fabricmc:yarn${project.yarn_mappings}:v2"'')
+  - Refresh the Gradle project in your IDE.
+  - Check and update any Mixin targets that may be outdated.
+=== Additional customization ===
+  * Specify from where to take your Java files with ''%%--%%input path/to/source''. Default: ''src/main/java''.
+  * Specify where to output the remapped source with ''%%--%%output path/to/output''. Default: 'remappedSrc'. You can use ''src/main/java'' here to avoid having to copy the remapped classes, but make sure you have a backup.
+  * Specify a custom place to retrieve the mappings from with ''%%--%%mappings some_group:some_artifact:some_version:some_qualifier''. Default: ''net.fabricmc:yarn:<version-you-inputted>:v2''. Use ''net.minecraft:mappings:<minecraft-version>'' to migrate to official Mojang mappings.
+=== Reporting issues ===
+Loom uses a fork of [[https://github.com/FabricMC/Mercury|Mercury]] to remap Java source code, for problems with remapping please report issues to its [[https://github.com/FabricMC/Mercury/issues|issue tracker]].