Porting a mod to a new Minecraft version

Why a port is work at all

Through 1.21.11, Minecraft shipped obfuscated: class and method names in the released jar were meaningless short strings that changed every build, because nothing was meant to depend on them. Mojang removed obfuscation starting with 26.1, the first calendar-versioned release, so a build from that point on ships with its real names intact.

That changes what a mapping set is for going forward, but not the underlying problem this guide is about. Mappings still exist to map obfuscated builds back to readable names, a mapping set is still specific to one Minecraft version, and every release before 26.1 still needs them. If you are porting across the 1.21.11-to-26.1 boundary, or supporting a version on either side of it, you are still dealing with two different naming systems either way.

Even with obfuscation gone, a port is still never just a version bump: names still get renamed as the game's own code is refactored, methods still change shape, and some things are simply removed. Real names instead of obfuscated ones make the diff easier to read, not the diff itself smaller.

Do it in this order

The mistake that makes ports drag on is fixing errors as they appear in the file you happen to have open. Work in layers instead.

1. Update the toolchain, before touching your code

Bump the Minecraft version, the mappings, the loader version and the API version in your build file. Nothing else. Then compile and look at the wall of errors.

That wall is your actual work list. Reading it before changing anything tells you whether this is a two-hour port or a two-week one, which is worth knowing before you start.

2. Fix the renames

Most of the errors will be one thing renamed. These are mechanical: find the new name, apply it everywhere.

Two things make this much faster:

• A mapping diff between the two versions, which tells you what became what, rather than guessing from similar names.
• Fixing all instances of one rename at once rather than file by file. The same method usually appears in a dozen places.

3. Fix the structural changes

What is left is real work: a method that changed signature, a class that split, a system that was replaced.

Here the loader's migration notes are worth reading properly, and so is the decompiled source. When a method is gone with no obvious replacement, search the decompiled game for its old behaviour and see what performs it now.

4. Fix the registration order

Both loaders move registration timings between versions more often than they change the registration API. Code that registered at the right moment can now be too early or too late.

These fail at runtime rather than at compile time and often produce confusing errors about something being absent, so they are worth checking deliberately rather than waiting to trip over them.

5. Then test behaviour

Everything compiles and loads. Now find the things that changed quietly: an event firing at a different point, a value that can now be null, an ordering that flipped.

Nothing errors here. Your mod is just wrong. This is the layer that produces bug reports a week after release, and the only defence is exercising your mod's actual features rather than confirming the game starts.

Start at the pre-release

The release cycle gives you a schedule if you use it:

• Snapshots. Things are still moving. Porting now means redoing it.
• Pre-releases. Feature complete, API mostly settled. This is when to start.
• Release candidates. If your port works here, it works on release day, because the release is usually this exact code.

Being ready on release day is worth more to your users than any feature you could have added that month, particularly for library mods, where everything downstream is waiting on you.

Supporting two versions at once

Two shapes, and picking wrong costs months:

Shared module plus per-version sources. One project, common code in one place, small version-specific source sets. Right when the differences are small.

Separate branches. Right when they are not. Once the versions diverge enough, keeping one codebase that satisfies both costs more than maintaining two, and produces code neither of you enjoys reading.

Be honest about which you are in. A shared module full of version checks is a branch that has not admitted it yet.

Publishing the port

• Declare the exact Minecraft versions in your release metadata, not just in the description. That metadata is what catalogues read, including the mod catalogue here, which filters on those exact declarations. Writing "1.21" when you mean every 1.21.x, or the reverse, is what makes users and catalogues disagree.
• Declare your loader. A build for one never runs on another. See why mods are loader specific.
• Bump your dependency ranges to what you actually tested against.
• Write a real changelog if behaviour changed. A port that silently alters a mechanic people built around is worse than one that says so.