Migrating Mappings using Loom

WARNING

For best results, it's recommended to update to Loom 1.13 or above, as it allows for migrating Mixins, Access Wideners and client source sets.

Migrating to Mojang Mappings

First, you need to run a migrateMappings command that will migrate your current mappings to Mojang Mappings. For example, the following command would migrate to Mojang Mappings for 1.21.10:

WindowsmacOS/LinuxIntelliJ

powershell

./gradlew.bat migrateMappings --mappings "net.minecraft:mappings:1.21.10"

./gradlew migrateMappings --mappings "net.minecraft:mappings:1.21.10"

migrateMappings --mappings "net.minecraft:mappings:1.21.10"

You can 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!

Editing Your Sources

By default, the migrated source code will appear in remappedSrc, rather than overwriting your existing project. You'll need to copy the sources from remappedSrc to the original folder. Make sure to back up the original sources, just in case.

If you are using Loom 1.13 or above, you can use the program argument --overrideInputsIHaveABackup to replace your sources directly.

WindowsmacOS/LinuxIntelliJ

powershell

./gradlew.bat migrateMappings --mappings "net.minecraft:mappings:1.21.10" --overrideInputsIHaveABackup

./gradlew migrateMappings --mappings "net.minecraft:mappings:1.21.10" --overrideInputsIHaveABackup

migrateMappings --mappings "net.minecraft:mappings:1.21.10" --overrideInputsIHaveABackup

Updating Gradle

If you are coming from Yarn, you can now replace your mappings in your build.gradle's dependencies section with Mojang Mappings.

groovy

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

You can now refresh the Gradle project in your IDE to apply your changes.

Final Changes

That's the bulk of the work done! You'll now want to go through your source code to check for any potentially outdated Mixin targets or code that was not remapped.

Tools like mappings.dev or Linkie will be helpful to familiarize yourself with your new mappings.

Migrating to Yarn

First, you need to run a migrateMappings command that will convert your current mappings to Yarn Mappings. This can be found on the Develop site under Mappings Migration. For example:

WindowsmacOS/LinuxIntelliJ

powershell

./gradlew.bat migrateMappings --mappings "1.21.10+build.2"

./gradlew migrateMappings --mappings "1.21.10+build.2"

migrateMappings --mappings "1.21.10+build.2"

Editing Your Sources

If you are using Loom 1.13 or above, you can use the program argument --overrideInputsIHaveABackup to replace your sources directly.

WindowsmacOS/LinuxIntelliJ

powershell

./gradlew.bat migrateMappings --mappings "1.21.10+build.2" --overrideInputsIHaveABackup

./gradlew migrateMappings --mappings "1.21.10+build.2" --overrideInputsIHaveABackup

migrateMappings --mappings "1.21.10+build.2" --overrideInputsIHaveABackup

Updating Gradle

If you are migrating from Mojang Mappings, you can now replace your mappings in your build.gradle's dependencies section with Yarn Mappings. Make sure to also update your gradle.properties file with the Yarn version specified on the Develop site.

gradle.properties

properties

yarn_mappings=1.21.10+build.2

build.gradle

groovy

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

You can now refresh the Gradle project in your IDE to apply your changes.

Final Changes

That's the bulk of the work done! You'll now want to go through your source code to check for any potentially outdated Mixin targets or code that was not remapped.

Tools like mappings.dev or Linkie will be helpful to familiarize yourself with your new mappings.

Additional Configurations

Migrating Split Sources

Loom 1.13 adds a new migrateClientMappings task that can be used to migrate your client sourceset to your new mappings. For example, to migrate to Mojang Mappings:

WindowsmacOS/LinuxIntelliJ

powershell

./gradlew.bat migrateClientMappings --mappings "net.minecraft:mappings:1.21.10"

./gradlew migrateClientMappings --mappings "net.minecraft:mappings:1.21.10"

migrateClientMappings --mappings "net.minecraft:mappings:1.21.10"

If you are using an older version of Loom, see other configurations.

Migrating Access Wideners

Loom 1.13 adds a new migrateClassTweakerMappings task that can be used to migrate your access wideners to your new mappings. For example, to migrate to Mojang Mappings:

WindowsmacOS/LinuxIntelliJ

powershell

./gradlew.bat migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.10"

./gradlew migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.10"

migrateClassTweakerMappings --mappings "net.minecraft:mappings:1.21.10"

Other Configurations

Specify where to take your Java source files from with --input path/to/source. Default: src/main/java. You can use this to migrate a client sourceset by passing --input src/client/java.
Specify where to output the remapped source with --output path/to/output. Default: remappedSrc. You can use src/main/java here to overwrite existing sources, 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.

For example, to migrate a client source set to Mojang Mappings in-place (overwriting the existing sources):

WindowsmacOS/LinuxIntelliJ

powershell

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

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

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

Block Entities