Migrating to Yarn or Mojang Mappings in a Java codebase

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 Mappings page.

Loom does not support migrating code written in Kotlin. Third party tools are available.

Note: Loom 1.13 is required for this process to handle Mixins.

These instructions cover migration from Yarn to Mojang Mappings.

1. 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.
2. 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.
3. Your migrated sources will appear in remappedSrc. Verify that the migration produced valid migrated code.
4. Copy the sources from remappedSrc to the original folder. Keep the original sources backed up just in case.
5. If you are coming from Yarn, you can now replace your mappings in your build.gradle's dependencies section with Mojang Mappings (i.e. mappings loom.officialMojangMappings()).
6. Refresh the Gradle project in your IDE.
7. Check and update any Mixin targets that may be outdated.

Your dependencies section should now contain this:

  dependencies {
      [...]
      mappings loom.officialMojangMappings()
  }

These instructions cover migration from Mojang Mappings (or an older version of Yarn) to Yarn.

1. Go 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.
2. 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.
3. Your migrated sources will appear in remappedSrc. Verify that the migration produced valid migrated code.
4. Copy the sources from remappedSrc to the original folder. Keep the original sources backed up just in case.
5. Update or add to your gradle.properties file with the Yarn version specified on the Develop site, i.e. yarn_mappings=1.21.10+build.2.
6. If you are coming from Mojang Mappings, you can now replace your mappings in your build.gradle's dependency section with Yarn's (i.e. mappings “net.fabricmc:yarn${project.yarn_mappings}:v2”)
7. Refresh the Gradle project in your IDE.
8. Check and update any Mixin targets that may be outdated.

Your dependencies section should now contain this, with the version of Yarn you are using specified in your gradle.properties:

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

At this time, users of split sources currently need to migrate their main source set with the process above, then do the process again, specifying the path to their client source set. As a reference, the command to migrate a client source set to Mojang Mappings is below.

  migrateMappings --mappings "net.minecraft:mappings:1.21.10" --input src/client/java

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

Loom uses a fork of Mercury to remap Java source code, for problems with remapping please report issues to its issue tracker.