[2020] Harmony - the full story

Hi everyone. A lot of hysteria and miss information runs around the community. So, let’s set this straight. I will try to keep this as simple as possible:

Part 1 - the beginning

I am the author and maintainer of a small library called Harmony. It does one thing: it allows mods to manipulate code in games. Mods usually put that library into their mod structure so users never see it (and shouldn’t).

It’s been around since RimWorld b12 and was stuck with version 1.2.0.1 for a long time. I was working on a version 2 that fixed a lot of design misses that 1.x had but it wasn’t backwards compatible so we all kept using 1.2.0.1

Part 2 - the move

Tynan contacted me about the move to the latest Unity a while ago. It looked like a clean cut to me and I saw a chance to introduce Harmony 2. We could separate the two scenarios and I wouldn’t have to make it compatible and co-existable with version 1.

We discussed different ways to integrate Harmony into the game and agreed upon to not put it directly into RimWorld because it might update more often than the game once the game is stable.

Part 3 - the hope

I had a short amount of time to finish Harmony 2 and test it with the new Unity version that Tynan wanted to use. It seemed to work and I was glad that he contacted me because their original plan was to release RimWorld with a Unity profile that wouldn’t have worked.

We agreed that I would create a small guide that would explain how to move things around and how to separate the two major versions of Harmony.

Then the unstable version was released and we had one week of testing it. My original plan was to release Harmony at the same time and call it a day. It had been in development for a year and people were using Harmony 2 outside RimWorld with success. Unfortunately, life isn’t that easy.

Part 4 - the pain

Soon after modders started using Harmony 2 as they were used to reports came in that it did not work as before. Mostly from modders that we’re complaining that it would not patch this or that. At first I thought I could just release a hotfix for Harmony 2, call it 2.0.0.1 and be done with it in time before everyone would implement it in their mods. But .1 became .2 and then .3 and so on.

By the time we reached 2.0.0.6 we had chaos. To understand why, you should know that Harmony is not working in isolation. Since mods will eventually want to patch the same function in the game, some coordination has to be done. This makes multiple versions running at the same time a very difficult thing to do (think rocket science level).

Part 5 - the discovery

While I was fixing the library more confusion arose. Some mods reported that their patches weren’t working even though they had the latest Harmony. After another period of confusion we finally found out why: something in the whole update process loads libraries different than before. The new version would not load more than one Harmony at the same time and I knew that the devs had not changed anything. But it was a fact that everyone had missed while preparing the release.

As a consequence the very first mod loaded that uses some version of Harmony will dictate that version to every other mod loaded later. That explained why all kind of confusing reports had come in. Either mods later got the wrong version at runtime or they got an older version that didn’t had the fixes in it as promised by me. It was a mess.

Part 6 - the solution

I realised that in order to control the chaos we had to control the first load of Harmony. I suggested that I could make an empty mod for it that would go first. Some people argued that HugsLib would be an alternative but that would tie Harmony releases to HugsLib releases. It also seemed that not everybody wanted HugsLib and it’s functionality.

So I went and created the Harmony mod. It’s sole purpose is to use the embedded Harmony lib to display its version on the title screen. Nothing more. I removed the library from my own mods and added a dependency to the new Harmony mod and it worked.

Part 7 - aftermath

While it did help with sorting out the underlying problem it was not able to solve the chaos that we created in the modding community. I understand that players want a stable and predictable game and we messed it up. I am deeply sorry for that. It was never meant to be like that.

Mods that still use any of the broken versions before Harmony 2.0.0.7 have to be updated at least to that version. The new Harmony mod will unify the library for everyone and with care I will maintain the Harmony library so any new releases will be compatible.

That works because the contact point between a mod and the library (the API) stays the same and a bait and switch to a later version in the Harmony mod will not require everyone to rush and use the latest version.

Part 8 - the future

We as modders learned a lot during this process. I hope you as users can forgive the chaos and establish a new trust in one of the major modding communities.

Over time people will understand that a mod isn’t just a mod and a dependency isn’t just something that will eventually abandoned. Maybe a new weird mod called Harmony can be at the top, weirdly above Core (no worries it doesn’t matter if it’s above or below, really). And I can keep up with all the fixes required in a patching library that made all those great mods possible.

Thanks Andreas Pardeike Brrainz

Edit 1: clarification that the library loading change wasn’t planed by anyone but just an unexpected side effect of updating Unity / .NET versions.

External link →