Migrating Mappings using Loom
Learn how to migrate your mod's obfuscation mappings using Fabric Loom.
WARNING
This page is written for version 1.21.10. Documentation for older versions may be incomplete.
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:
./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.
./gradlew.bat migrateMappings --mappings "net.minecraft:mappings:1.21.10" --overrideInputsIHaveABackup./gradlew migrateMappings --mappings "net.minecraft:mappings:1.21.10" --overrideInputsIHaveABackupmigrateMappings --mappings "net.minecraft:mappings:1.21.10" --overrideInputsIHaveABackupUpdating Gradle
If you are coming from Yarn, you can now replace your mappings in your build.gradle's dependencies section with Mojang Mappings.
dependencies {
[...]
mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
mappings loom.officialMojangMappings()
}2
3
4
5
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:
./gradlew.bat migrateMappings --mappings "1.21.10+build.2"./gradlew migrateMappings --mappings "1.21.10+build.2"migrateMappings --mappings "1.21.10+build.2"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.
./gradlew.bat migrateMappings --mappings "1.21.10+build.2" --overrideInputsIHaveABackup./gradlew migrateMappings --mappings "1.21.10+build.2" --overrideInputsIHaveABackupmigrateMappings --mappings "1.21.10+build.2" --overrideInputsIHaveABackupUpdating 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
yarn_mappings=1.21.10+build.2build.gradle
dependencies {
[...]
mappings loom.officialMojangMappings()
mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
}2
3
4
5
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:
./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:
./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 usesrc/main/javahere 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. Usenet.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):
./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"