Every now and then, there is a new minecraft subversion, and when your favourite server updates, you need to update as well. Which is easy if you’re running a plain vanilla client, but can be quite an annoyance when you’re using mods, and your mod author doesn’t update them in time.

When there’s a lot of changes to the client itself, then, well, mods have to adjust to these changes. But when the changes are very minor, like 1.12 to 1.12.1 to 1.12.2, most of the time, plugins will still work.

As long as they’re forge mods. Not so, with liteloader.

The problem behind this is, Mojang obfuscates their client classes, meaning they assign more or less random meaningless names to them, like abc or aj or bcx. And, in new versions of the client, this mapping changes; the class that used to be abc may be abf now.

The people who wrote the Minecraft Coder Pack, the software that Forge and LiteLoader build on, made tables to reverse map those names to meaningful ones, and they do that for every new version of Minecraft. So, when your mod is using code that accesses a block int the world, you use the BlockState class; when your mod is loaded, that name – BlockState – needs to be mapped to the name the client is using – bcj, or bcx, or whatever.

Forge does this dynamically. The .jar still used the BlockState name; when the mod gets loaded, that name gets translated to the real name of the client you’re currently using. That’s why small updates to the client don’t cause Forge mods to break.

LiteLoader, on the other hand, does this translation while you compile the mod. This means the translation phase – and the time associated with that – is running before mods are distributed, your whatever.litemod already references the bcj name. This allows for faster loading – which is one of the reasons why Liteloader is lite – but it means your mod breaks when bcj becomes bcx and your mod still references bcj.

I’m a big fan of the VoxelMap mod, and unfortunately, when my server changed to 1.12.2, there was no VoxelMap available. So I said to myself, maybe there’s a way to change those mappings within the mod?

Turns out there is.

You need three things – the obfuscated/readable mapping list for the old and the new version, and the software that does the remapping

The software that does the remapping itself is called SpecialSource, and it’s available from https://github.com/md-5/SpecialSource/releases.

The mapping files – if you are developing mods yourself, then they should already be present in your .gradle/caches/minecraft/de/oceanlabs/mcp/mcp_snapshot directory. On linux, .gradle is in your home directory; on windows, it’s in %APPDATA%. There are more subdirectories – one that has a date, then a minecraft version, then srgs/notch-mcp.srg and mcp-notch.srg. You need the notch-mcp.srg for the version the litemod is in, and the mcp-notch.srg for the version you want to create.

If you don’t, you need to create them; they’re created automatically when you’re setting up forge. Download both forge mdks, the one for the source version and the one for the target version. Extract each of them to some directory, and run gradlew SetupDecompWorkspace in each directory. Unfortunately, they’re ultimately put together from other files that get downloaded; you can’t download them directly. So you need to run the gradle step.

Anyway, once you have the SpecialSource.jar, and the two mapping .srg files, run the following commands (example is for 1.12 to 1.12.2, adjust as needed):

java -jar /path/to/SpecialSource.jar -i mod-whatever-1.12.litemod -m /path/to/1.12/srgs/notch-mcp.srg -o mod-whatever-mcp.litemod
java -jar /path/to/SpecialSource.jar -i mod-whatever-mcp.litemod -m /path/to/1.12.2/srgs/mcp-notch.srg -o mod-whatever-1.12.2.litemod

The first of these commands takes your old mod (-i), maps it using the notch to mcp mapping (-m), and writes an intermediate litemod file (-o).
The second one used the intermediate file (-i), maps mcp to notch for the new version, and writes it to a new litemod file.

The next thing to do is adjust the json description. Litemod files have a component that tells them which client version they are for; we want the new litemod to have the correct name.

On Linux, I just use the command line:

unzip mod-whatever-1.12.2.litemod litemod.json
sed -i s/mcversion/s/1.12/1.12.2/g litemod.json
zip -r mod-whatever-1.12.2.litemod litemod.json

If you prefer, just use a zip program to extract the litemod.json file; a text editor to edit it, and the zip program to replace it afterwards.

And, lo and behold, we have a mod that works with our new minecraft version!

Again, to put everything together:

• Make sure you have a current version of java available.
• Download SpecialSource.jar from https://github.com/md-5/SpecialSource/releases
• Download the mdk for the source and the target version of your mod from https://files.minecraftforge.net/
• Extract each of the mdk zips to a directory. In each of the directories, run gradlew SetupDecompWorkspace.
• Search for the notch-mcp.srg and mcp-notch.srg files in the .gradle/caches/minecraft/de/oceanlabs/mcp/mcp_snapshot folder; you want the notch-mcp.srg from the folder that has the version name of your mod (source version), and the mcp-notch.srg from the folder that has the version name of your client (target version). The .gradle folder is in %APPDATA% on Windows, and in $HOME on Linux.
• Run the SpecialSource jar twice to map from old to intermediate and from intermediate to new. Adjust paths and version numbers as needed:
java -jar /path/to/SpecialSource.jar -i mod-whatever-1.12.litemod -m /path/to/1.12/srgs/notch-mcp.srg -o mod-whatever-mcp.litemod
java -jar /path/to/SpecialSource.jar -i mod-whatever-mcp.litemod -m /path/to/1.12.2/srgs/mcp-notch.srg -o mod-whatever-1.12.2.litemod

• Use a zip program to extract the litemod.json file from your new litemod file, change the version number in the line that says mcversion, and move the changed file back into the .litemod.
• Load the new .litemod in Minecraft, and celebrate.