CitiesHarmony.API 2.2.0

dotnet add package CitiesHarmony.API --version 2.2.0                
NuGet\Install-Package CitiesHarmony.API -Version 2.2.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CitiesHarmony.API" Version="2.2.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CitiesHarmony.API --version 2.2.0                
#r "nuget: CitiesHarmony.API, 2.2.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install CitiesHarmony.API as a Cake Addin
#addin nuget:?package=CitiesHarmony.API&version=2.2.0

// Install CitiesHarmony.API as a Cake Tool
#tool nuget:?package=CitiesHarmony.API&version=2.2.0                

CitiesHarmony

NuGet Badge

This C:SL mod provides Andreas Pardeike's Harmony patching library (version 2.2.2) to all mods that require it.

It hotpatches older Harmony versions (1.2.0.1 and 1.1.0.0) and adds limited cross-compatibility for Harmony 1.0.9.1. All of those versions are still used by various mods. The patching is necessary because Harmony 1.x is incompatible with 2.x.

The bundled CitiesHarmony.Harmony.dll (a fork of 0Harmony.dll) contains additional bug fixes that are specific to the mono runtime of Cities: Skylines.

The associated Steam workshop item will be updated to the latest stable Harmony 2.x version in periodic intervals. By relying on a single CitiesHarmony.Harmony.dll for all mods, we can make sure that all mods use the latest version it that includes all bug fixes.

By using auto-subscription, it is possible to migrate existing mods to Harmony 2.x without causing disruptions for users!

Documentation for Mod Developers

API Package Installation

To use Harmony 2.x in your mod, add the CitiesHarmony.API nuget package to your project. The package includes the latest version of Harmony as well as the HarmonyHelper that is used to access it.

Make sure that when you build your mod:

  • The CitiesHarmony.API.dll is copied to the AppData mod directory
  • The CitiesHarmony.Harmony.dll is not copied to the AppData mod directory (it is provided by the central Harmony mod)

Depending on the version of Visual Studio, the project style and the post-build script you are using, there are different ways to achieve that:

  • If you are manually copying the assemblies to AppData mod directory, make sure to copy only the DLL of your mod and the CitiesHarmony.API.dll, not the CitiesHarmony.Harmony.dll.
  • If you are using the old Visual Studio project style (packages.config) with a post-build script, set "Local Copy" to true for CitiesHarmony.API reference and to false for CitiesHarmony.Harmony reference (check out the example in ExampleMod.OldStyle folder).
  • If you are using the new Visual Studio project style (like the example mod in this repository) with a post-build target, no action is required after installing the Nuget package! It is configured so that CitiesHarmony.Harmony is not copied to the target directory (check out the example in ExampleMod folder).

API Usage

Make sure that there are no references to HarmonyLib in your IUserMod implementation. Otherwise the mod could not be loaded if CitiesHarmony is not subscribed. Instead, it is recommended to keep HarmonyLib-related code (such as calls to PatchAll and UnpatchAll) in a separate static Patcher class.

Before making calls to harmony in your code, you need to query CitiesHarmony.API.HarmonyHelper to see if it is available. There are 3 different hooks for that purpose:

  • void HarmonyHelper.DoOnHarmonyReady(Action): Will invoke the passed action when Harmony 2.x is ready to use. This hook should be called from IUserMod.OnEnabled. If the Harmony mod is not installed, this hook will attempt to auto-subscribe to it.
  • void HarmonyHelper.EnsureHarmonyInstalled(): If you don't want to apply your patches in IUserMod.OnEnabled, call this method instead. It will perform the same auto-subscription as DoOnHarmonyReady
  • bool HarmonyHelper.IsHarmonyInstalled: Returns true is Harmony is ready to be used. When queried, this hook will not attempt to auto-subscribe to the Harmony workshop item. Use this hook for all kinds of unpatching, applying patches in the LoadingExtension or while the simulation is running.

Take a look at the example mod in this repository for further inspiration!

It is recommened to add this mod as a dependency to your workshop item for transparency reasons.

Alternative A: Applying your patches in OnEnabled/OnDisabled
public class Mod : IUserMod {
    // ...

    public void OnEnabled() {
        HarmonyHelper.DoOnHarmonyReady(() => Patcher.PatchAll());
    }

    public void OnDisabled() {
        if (HarmonyHelper.IsHarmonyInstalled) Patcher.UnpatchAll();
    }
}
Alternative B: Applying your patches in LoadingExtensionBase
public class Mod : LoadingExtensionBase, IUserMod {
    // ...

    public void OnEnabled() {
        HarmonyHelper.EnsureHarmonyInstalled();
    }

    public override void OnCreated(ILoading loading) {
        if (HarmonyHelper.IsHarmonyInstalled) Patcher.PatchAll();
    }

    public override void OnReleased() {
        if (HarmonyHelper.IsHarmonyInstalled) Patcher.UnpatchAll();
    }
}
Example Patcher Class
public static class Patcher {
    private const string HarmonyId = "yourname.YourModName";
    private static bool patched = false;

    public static void PatchAll() {
        if (patched) return;

        patched = true;
        var harmony = new Harmony(HarmonyId);
        harmony.PatchAll(typeof(Patcher).Assembly); // you can also do manual patching here!
    }

    public static void UnpatchAll() {
        if (!patched) return;

        var harmony = new Harmony(HarmonyId);
        harmony.UnpatchAll(HarmonyId);
        patched = false;
    }
}
Product Compatible and additional computed target framework versions.
.NET Framework net35 is compatible.  net40 was computed.  net403 was computed.  net45 was computed.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories (2)

Showing the top 2 popular GitHub repositories that depend on CitiesHarmony.API:

Repository Stars
CitiesSkylinesMultiplayer/CSM
Source code for the Cities: Skylines Multiplayer mod (CSM)
CitiesSkylinesMods/TMPE
Cities: Skylines Traffic Manager: President Edition
Version Downloads Last updated
2.2.0 1,674 1/14/2023
2.1.0 2,109 2/8/2022
2.0.0 6,426 2/14/2021

Update to Harmony 2.2.2