Hello MenschLennart,

The CitiesHarmony.API should work with either Harmony mod (boformer's, or mine). If you have missing dependencies, most likely you have missed something. Once you install boformer's CitiesHarmony.API from nuget.org into Visual Studio, this will provide both the API, and the Harmony library itself. However, this does not create references to the game's assemblies, so those dependencies need to be added manually. Ie, you'll be able to call HarmonyLib.Harmony functions, but not ICities functions to access game data.

To access game data, you need to add file references to your mod project to C:\References\Assembly-CSharp.dll and C:\References\ColossalManaged.dll, which you should copy from the game's distributed files.

There is not yet a published API for Harmony (redesigned), nor specific examples to go with it, but I'm working on both API and examples as we speak, as I have implemented some requested and needed features. My API and examples will be published before or around the same time as this new game update comes on Wednesday.

What dependencies are wrong or missing in your project? If you give some more detail, myself or someone else may be able to give specific feedback

Hey Chaos,
thanks for your response. I got it to work and I updated a abandoned mod to use your version of harmony. I thought the current API from Boformer is not the right way to go. But to hear it, that's fine to use it with your harmony I'm good to go and will try it.

Thanks :)

Hey Chaos, I wanted to ask where the update is you talked about coming before or with the dlc release. Im just wondering. You are saying in lot topics and comments, that an update will come soon since march 2021, but it's still not there.

@MenschLennart, I'm working on it right now.

I had planned to have it ready yesterday before the Airports release, but miscalculated the Airports release time, and ended up spending all of yesterday fielding support questions relating the update, instead of finishing the API.

I originally intended to do all this work in march last year, but due to politics, I ended up laying low and not stirring the pot.

Right now it looks like CO is planning to update their harmony to 2.2 of the library, which forces me to support it also. My API would have been "nice to have" last year, but now it's required. I looked at the change boformer did, and the versioning hacks he's doing will break the workshop once more next week when he releases 2.2 to the main harmony mod. I think this time the breakages will be more subtle than they were in last Feb's disastrous update.

Also, a genuine bug was found in my Harmony yesterday (https://github.com/drok/Harmony-CitiesSkylines/issues/20), which does not impact the API, but I got sidetracked a bit considering what ramifications it would have. I now have a plan on how to release that fix.

Long story short, I'm actively working it right now, it's my top priority to get it out and clean ASAP. To be sure, when I push it to nuget.org it will have no rushed or cut corners. I appreciate your patience.

Okay, first thanks for the update. So I'm curious whats coming.
How do you see what boformer did? The only thing whats updated for now on his github is an updated version number. Nothing more. Is there a source you have access to the community dont have?

Originally posted by MenschLennart:

Okay, first thanks for the update. So I'm curious whats coming.
How do you see what boformer did? The only thing whats updated for now on his github is an updated version number. Nothing more. Is there a source you have access to the community dont have?

I only have access to the github log in his two repos (CityHarmony and Harmony), and I have also downloaded and decompiled the "experimental" distributed files. My conclusions are based on what I saw in these two sources.

Here are the actions that I found important:

• Boformer merged from upstream (pardeike/Harmony @ v2.2.0.0 label) to his own fork
  
• he edited that fork to rollback the assembly version from 2.2.0.0 to 2.0.4.0: https://github.com/boformer/Harmony/commit/72ac7ca8b5ceb387b873ca9053e4ef81fa35e1b0 - this is a very troubling action, because a 2.2 interface is now masquerading as 2.0.4.0, so future mods that are linked against the masquarade, use 2.2 functions, and are being run in an environment where only the genuine 2.0.4.0 is available (eg, my own Harmony), will fail with TypeLoadExceptions due to the 2.2 functions which are required but do not exist in 2.0.4.0 assemblies.
  
• he labeled the release/mod as 2.2-0
  
• pushed to his experimental item, requested that people "test" it for him
  
• plans to release it to the main channel in 1 week

This will cause subtle breakage that will make it look like my harmony is "not compatible"

It's subtle because nothing bad will happen immediately, in fact his "test" will show no problems, until the first mod meets the following criteria:

1. he releases a new API that uses the 2.2 as dependency, but labelled 2.0.4.0
   
2. some modder decides to use one of the newly available 2.2 functions, like HarmonyLib.GetOriginalMethod()
   
3. that mod is run with Harmony Redesigned instead of boformer

This scenario will eventually happen, but his "test" methodology based on people trying it will not uncover the latent problem he seeds now.

I've also looked at the state of the upstream, at pardeike's recent work, there is a lot of new activity since the 2.2.0.0 release in december, including bugfixes to that release. This means that boformer's upcoming update already will contain bugs that we know of, and are already fixed upstream.

I would not bring the 2.2 release to cities skylines at all until it matures, because (a) it brings no must-have-now features, but since CO is going to bring this, I have to plan for it myself.

His test method is no method at all, just a casual "lets pull new stuff because some modder asked about it", and release it to 1M users with just some casual "experiment", but no considering the full impact and compatibility with the existing ecosystem.

On top of this, CO is preventing me from updating my harmony on the workshop. As it is, it works great, and I have a plan to update it in the future, but for now it only offers 2.0.4.0 functionality, and does so very reliably.

The API is not impacted much by all this, because it's agnostic of the version of the installed Harmony at runtime, and will work with both CO's 2.2 harmony, and my own 2.0.4.0 harmony, and eventually 2.2, but I need to build into the API the provision to install Harmony Redesigned if not already present. That install, which will happen from Github, is already implemented, and being tested, but since he decided to push 2.2 now, my API must implement the on-demand install and update from GitHub flawlessly.

So there's a ton of work that is already done. my API is already doing the updating, the next harmony mod release also does updating from github, but I need to test it a bit more to make sure they can handle the update to 2.2 flawlessly at first release, which is the nuget I had planned to release yesterday, and now I have to push back for a day or two. (his 2.2 announcement came yesterday, amid the Airports breakage chaos)

I do apologize for the delay in releasing the API, but I really do need it to account for the upcoming Harmony 2.2 by Colossal Order. This is so that mods you write, which rely on my API, will work, by design, especially in the odd corner-cases. Or at least not cause Harmony-related faults.

This 2.2 compatibility is not something I had planned on, but my harmony and the API, and any mods you make with it will much better off if the API is ready and able to handle such impromptu updates.

I didn't mean to offend you with my question. It's just that I've already read a lot from you, where you say that you'll soon bring out an update. Only nothing has happened for almost a year. So I was a little bit suspicious if such an update will come at all.

Until it does, you can't expect developers to use your Harmony mod. I won't until then because I don't want to risk betting on the wrong horse.

Originally posted by MenschLennart:

I didn't mean to offend you with my question. It's just that I've already read a lot from you, where you say that you'll soon bring out an update. Only nothing has happened for almost a year. So I was a little bit suspicious if such an update will come at all.

Until it does, you can't expect developers to use your Harmony mod. I won't until then because I don't want to risk betting on the wrong horse.

No problem, I would feel the same in your shoes.

Keep in mind that no matter what API you choose, the end-users decide in the end which harmony they want to use. Both APIs work with both Harmony mods. The developers don't have much say over which harmony mod ends up being used.

The question over one API vs the other is to do with how reliable that API is, whether you'll be required to update your mod (and pull a new API with possibly new bugs) when the Harmony mod itself is updated, and how prone to run-time (on the user's machine) your mod will be. Will the end users have a rock-solid experience, or will they encounter unexplained errors due to a loose API that you've made some small mistake with?

It's not a horse betting exercise.

In any case, I salute you for choosing the API with more history behind it rather than the newly released one. Having people rely on my first API version does put quite a bit of stress on me, because I don't want to expose my developers to some corner case that is my responsibility to handle, as the API maker.

No worries, the two competing APIs are close enough in wording and specification that you should be able to switch from one to the other with minimal rework, whenever you want :)