• 26.2
• 26.1.2
• 1.21.11
• 1.21.10
• 1.21.8
• 1.21.4
• 1.21.1
• 1.20.4

Migrating Mappings using Ravel

Learn how to migrate your mod's obfuscation mappings using Ravel.

WARNING

This page is written for version 1.21.10. Documentation for older versions may be incomplete.

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 Tweaker, 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!

Prerequisites

INFO

Ravel 0.3+ now includes downloader for Yarn and Mojang Mappings, so you can skip this section.

First, you need to get your mappings. For remapping from Yarn to Mojang Mappings or vice versa, you need to download both of them.

• Find and download Yarn mappings, choose the mergedv2.jar, extract it as a ZIP. The mappings is in mappings/mappings.tiny file.
• Download Mojang mappings by searching for your Minecraft version, open the JSON url, search for client_mappings, and download the client.txt

Remapping

Next, right click 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.

• 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.10+build.2 

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.