Migrating Mappings using Ravel

WARNING

Mappings are not officially supported on 26.1. Before updating a mod that is using Yarn Mappings to 26.1, migrate to Mojang Mappings before changing the Minecraft dependency. The following docs assume you are using 1.21.11.

Ravel is a plugin for IntelliJ IDEA to remap source files, based on IntelliJ's PSI and Mapping-IO. It supports remapping Java, Kotlin, Mixins (written in Java), Class Tweakers, and Access Wideners.

Install it from JetBrains Marketplace or download the ZIP file from GitHub Releases and install it by clicking the gear icon on the plugin settings and clicking Install Plugin From Disk.

Migrating Mappings

WARNING

Commit any changes before attempting to remap your sources! Do not modify your gradle.properties or build.gradle yet!

Start by right clicking on a file open in the Editor and choose Refactor > Remap Using Ravel

A dialog like this will open. You can also open the dialog by clicking Refactor from the top menu.

Next, add the mappings by clicking the + icon. Click the download option if you don't have them already.

INFO

If you do not see the download button, update Ravel to 0.3 or above.

• For migrating from Yarn to Mojang Mappings, add the Yarn mappings.tiny file first, choose named as the source namespace and official as the destination namespace. Then, add the Mojang client.txt file and choose target as the source namespace and source as the destination namespace.
• For migrating from Mojang Mappings to Yarn, add the Mojang client.txt first, this time choosing source as the source and target as the destination. Then, add the Yarn mappings.tiny and choose official as the source and named as the destination.

Then, select the modules that you want to remap by clicking the + icon, or the icon on its left to add all modules.

Then, click OK and wait for it to finish remapping.

Updating Gradle

After the remapping finished, replace your mappings in your mod's build.gradle.

dependencies {
    mappings "net.fabricmc:yarn:${project.yarn_mappings}:v2"
    mappings loom.officialMojangMappings() 
    // Or the reverse if you're migrating from Mojang Mappings to Yarn
}

Also update your gradle.properties, remove yarn_mappings option or update it to the one you use.

yarn_mappings=1.21.11+build.3 

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.

For problems that are detected by Ravel, you can search (Ctrl+Shift+F) for TODO(Ravel).

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