I am a Chaos Management Consultant, but the full name doesn't fit.

You'll find more structure and organization in my mods than you imagined possible in a free mod. I'm a pretty old guy, I don't like quick hacks.

The Harmony Report is the mods way of providing feedback to you about how harmoniously your mods are inter-operating. It is appended to the game log file (output_log.txt) when exiting to desktop, and contains info about mod conflicts, missing dependencies, exceptions, etc.

Although the two mods share the name and some of the goals, boformer's Harmony is broken by design, and causes major instability affecting among all mods, whether they use it or not. This makes it an undependable dependency.

On the other hand, this library's top priority is stability; updates will be minimized, and thoroughly tested on the Beta channel before release for general use.

This mod informs the player with actionable messages via the Harmony Report of any conflicts, bringing solutions within your reach. Boformer's mod gives no feedback, requiring much guesswork and frustration.

There is a Diagnostics for Harmony mod which is a companion to this mod, intended for developers, which will provide more in depth error reports, to help shorten debugging their own mods.

This project actually intends to bring harmony to the Cities Skylines modding community, and thus deserves to use the name Harmony.

The other library would be more aptly named "Experiments with a compiler and the Harmony Library" or "Bugs and Exceptions Fresh to you Every Other Week". There is simply nothing harmonious about it.

This mod manages many versions of the Harmony library, backwards compatibility with all previous versions of boformer's mod and APIs, and as such labeling it with one single number can be misleading. If you must know the current version number of this mod, it is shown in the change notes.

YES.

It is the explicit goal of this library to be compatible with all past API releases. An API is a specification; a promise by its publisher to provide service to compliant mods. This mod honours all past promises (API's). This is a key difference between boformer's mod and this one. When he "updates" his mod, all previous APIs are obsolete, and all mods must update to the API of the day. A promise that is reneged at his whim is no promise at all.

The main purpose for this mod's existence is exactly this; to answer "YES" to this very question.

The API's released so far are:

• CitiesHarmony.API v1.0.3 - uses 0Harmony.dll v2.0.0.9
  
• CitiesHarmony.API v1.0.4 - uses 0Harmony.dll v2.0.0.9
  
• CitiesHarmony.API v1.0.5 - uses 0Harmony.dll v2.0.1.0
  
• CitiesHarmony.API v1.0.6 - uses 0Harmony.dll v2.0.4.0
  
• CitiesHarmony.API v2.0.0 - uses CitiesHarmony.Harmony.dll v2.0.4.0

Yes.

Similar to boformer's mod, this mod transfers the patches from 0Harmony 1.x transparently to the 2.x library, and installs redirection patches, so 1.x libraries will in fact be using the current 2.x library. Versions 1.2.0.1, 1.1.0.0 and 1.0.9.1 are supported.

• This mod will be updated infrequently.
  
• Bugfixes from Andreas's published work will be pulled ASAP, tested via the Beta channel, and released to this channel, after no less than two weeks of beta testing.
  
• New Features from upstream (ie, future releases) will likely not be imported at all, except if there is a lot of demand by the mod developers and is backed by a very good reason.
  
• New features and bugfixes to this mod, ie, the Harmony Report, or API feature additions will be tested in Beta for at least two weeks before general release.

I have plans to greatly improve error and exception tracking, as well as to implement an API that gives mod developers visibility into potential or existing conflicts; these are features that will improve the overall quality of all mods in the CSL workshop.

Network Extensions 2 is a finely crafted piece of software, and works great with or without Harmony. Previously, after releasing the Feb 14 update to his Harmony, boformer claimed it, and other mods, were broken and needed to be "updated", but the bug is the way his Harmony mod works. A clear, convincing description of the supposed bug with NEXT2 or other mods was never given.

This drop-in replacement Harmony has no known issues with NEXT2.

No mods need to be updated, players can simply switch from boformer's Harmony to this one at any time. You can also switch back if you want.

For developers, there will be an API release named "Harmony-CitiesSkylines", which will be published to the nuget repo after testing is complete. This will be a drop-in replacement for "CitiesHarmony.API". The difference is that it auto-subscribes to workshop item 2399343344 (this one) instead of 2040656402 (boformer's Harmony). No other changes are needed, and switching to this API is not required. Your subscribers have the ability to switch.

You can, however, change the Required Items list on your mod's workshop page to point to this one instead. This will not affect existing subscribers, but new subscribers will be prompted to install this mod. If they already have boformer's Harmony subscribed, there will be a conflict, and boformer's will need to be unsubscribed.

The Harmony mod hooks the game's exception panel, in order to capture and analyse mod errors. The result of the analysis is that it attributes the source of each exception to possibly two mods; the triggering mod is the one that made some request that ultimately resulted in an unhandled exception, and the throwing mod is the one that was unable to handle the (possibly faulty) request.

In some cases, a mod triggers a bug in the game; in this case only the trigger point is shown on the Harmony Report. The full stack trace is in the log file also.

Exceptions are also filtered. Every mod is permitted up to three errors, after which no more pop-ups wil be shown. The exceptions will still be logged, but the game session will not be interrupted by the exception window.

Note that the limit of three applies to errors of any kind, so if a mod has two missing dependencies, it will only be allowed one exception pop-up; one that has three or more other problems will not show a pop-up at all. The logic is that mods for which errors are a common occurrence should not disrupt the game, while mods where an exception is truly an unusual event, do need attention.

In any case, the Harmony Report will contain a summary of all exceptions, whether suppressed or not.

Missing dependencies are loose ends that the mod's author has overlooked. Only the mod author can resolve them, so a bug report should go out to the respective mod.

Missing dependency severity can range from benign to breaking.

• mscorlib[4.0.0.0]
  
• System[4.0.0.0]
  
• System.Core[4.0.0.0]
  
• System.Xml [4.0.0]

These indicate the developer targeted the wrong .Net framework ( .Net 4.0 instead of .Net 3.5). This is similar to compiling a program for the wrong version of Windows. The program will mostly work fine, thanks to Microsoft's care to provide backwards compatibility, but some features which require a specific version of the .Net. It's not possible to tell what will and will not work, but the developer will be able to sort it out once he/she correctly compiles his mod.


Some mods interact with others, like TM:PE, but have not kept up updating when TMPE was updated. When they were written, a particular version of TMPE may have been current, but is now out-of-date. TMPE's functions have likely changed, and what worked then works differently now, or has been removed. It is not possible to automatically match-up different versions. The outcome is that a mod that is missing this dependency probably has a function that used to work, but no longer works. Examples:



Some mods require other mods to be present, but you have not installed the requirement. Sometimes the mod author forgot to add the requirement on their mod's page, or perhaps there was a downloading error, etc.

In some cases, the mod with the dependency is not coded to fail graciously when its dependency is missing, and will simply crash when you invoke some feature that requires that missing mod.

Just because a dependency is missing is not itself a fatal error, but it means a crash, error, or missing functionality should be expected from the affected mod, if/when the right circumstances are met (ie, when the missing mod is invoked and cannot be found).

In all cases, missing dependencies should be reported to the respective mod authors.

The Harmony Report brings forward these hazards, in order to give early warnings of expected problems. It is my intent that by making these problems visible, the various authors will gradually clean up their mods, thus removing instability from the mod ecosystem.

The following error is a feature of the Harmony Redesigned mod:


This error happens when a mod attempts to remove all patches installed by all mods, typically when it returns to the main menu or exits the game. It is a common programming error, as each mod should only uninstall its own patches, not usually another mod's patches, and never Harmony's own installed patched (eg, those that capture errors, or translate 0Harmony 1.2.0.1 request to 2.x requests for compatibility)

The old mod ignores this error, and as a result allows mods to corrupt each other. One outcome is the frequently given advice to "never double load". This programming error is why the main menu doesn't work when some mods are installed, and why double loading is discouraged. Broken mods corrupt the state of all mods when they exit a city.

The fix is not to avoid double loading, but to report the problem to the lazy programmers and get them to fix their crap code, not teach you how to not step in it.

There is a limit of about 25k characters for the pop-up exception panel's text field, which means a full Harmony report would not fit in some cases where many mods are in use.

Therefore, in the Content Manager, when clicking Harmony's REPORT button, only an abridged report is shown, which contains only mods that have some problem. Only potentially severe problems are shown.

On the other hand, the Harmony Report ouput to the output_log.txt log file is the full report, showing every mod that was present, the order mods were loaded, any triggered or thrown exceptions, missing dependencies, illegal accesses, etc.

When you request help, please include the "Final Harmony Report", which is written to the log file when you exit the game. It's the most complete view of the report.

Also, interim reports are generated when a city is loaded, which may be useful to show the state of your mod ecosystem before simulation started. This can help distinguish between errors that occurred during initialization or during simulation.

If you disable the Harmony mod, all other mods that require use of the Harmony library will fail with "Harmony is disabled" if they attempt to use the library.

This feature is mainly useful for developers to test if their mods are partially functional if Harmony is unavailable. A well written mod should not crash and burn when this condition happens. If there is some function the mod could offer to the end user without having the benefit of patching, it should do so, otherwise, it could log some actionable message to a log, if appropriate, but in no case take down the whole game due to their failure.

This error can also occur if there is some conflict with harmony itself, in which case it will chose to remain disabled, rather than behave unpredictably.

It is easier and quicker to diagnose a problem that is reproducible and unambiguous than one that happens intermittently and unexpectedly. In this case, Harmony is just making it easier to find and fix the issue than the old Harmony.